idnits 2.17.1 draft-wu-netmod-base-notification-nmda-02.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 is 1 instance of too long lines in the document, the longest one being 16 characters in excess of 72. ** The abstract seems to contain references ([RFC8342]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 224 has weird spacing: '...eration enu...' -- The document date (February 28, 2019) is 1877 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: 'RFC8040' is mentioned on line 76, but not defined == Missing Reference: 'RFC8174' is mentioned on line 110, but not defined == Missing Reference: 'RFC8340' is mentioned on line 206, but not defined == Missing Reference: 'RFC7950' is mentioned on line 615, but not defined == Unused Reference: 'RFC6020' is defined on line 650, but no explicit reference was found in the text == Unused Reference: 'RFC8072' is defined on line 672, but no explicit reference was found in the text == Outdated reference: A later version (-12) exists of draft-ietf-netmod-nmda-diff-00 ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group Q. Wu 3 Internet-Draft C. Feng 4 Intended status: Standards Track R. Ranade 5 Expires: September 1, 2019 Huawei 6 February 28, 2019 8 NMDA Base Notification for Applied Intended Configuration 9 draft-wu-netmod-base-notification-nmda-02 11 Abstract 13 The Network Configuration Protocol (NETCONF)and RESTCONF provides 14 mechanisms to manipulate configuration datastores. NMDA introduces 15 additional datastores for systems that support more advanced 16 processing chains converting configuration to operational state. 17 However, client applications are not able to be aware of common 18 events in these additional datstores of the management system, such 19 as a applied configuration state change in NETCONF server or RESTCONF 20 server, that may impact management applications. This document 21 define a YANG module that allows a client to receive additional 22 notifications for some common system events pertaining to the Network 23 Management Datastore Architecture (NMDA) defined in [RFC8342]. 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 September 1, 2019. 42 Copyright Notice 44 Copyright (c) 2019 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 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. NMDA Base Notifications for applied intended configuration . 3 62 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.2. Data Model Design . . . . . . . . . . . . . . . . . . . . 5 64 2.3. Relation with NMDA Datastore Compare . . . . . . . . . . 7 65 2.4. Definitions . . . . . . . . . . . . . . . . . . . . . . . 8 66 3. Security Considerations . . . . . . . . . . . . . . . . . . . 14 67 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 68 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 69 6. Normative References . . . . . . . . . . . . . . . . . . . . 15 70 Appendix A. Changes between revisions . . . . . . . . . . . . . 16 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 73 1. Introduction 75 The Network Configuration Protocol (NETCONF) [RFC6241] and RESTCONF 76 [RFC8040] provides mechanisms to manipulate configuration datastores. 77 NMDA introduces additional datastores (e.g., , 78 ) for systems that support more advanced processing 79 chains converting configuration to operational state. However, 80 client applications are not able to be aware of common events in 81 those additional datastores of the management system, e.g., there are 82 many background system activities (e.g.,the system moving the config 83 from running->intended->operational,NMDA datastore consistency 84 checking [I-D.ietf-netmod-nmda-diff]) that happen during the time 85 that configuration is committed to to the time that the 86 configuration is actually applied to . It is possible 87 that some configuration could not be applied to due to 88 either validation issues, or missing resource, etc. There is a need 89 for user to know the applying result of datastore and the 90 reason why the configuration were not applied. 92 This document define a YANG module that allows a NMS client to 93 receive additional notifications for some common system events 94 pertaining to the Network Management Datastore Architecture (NMDA) 95 defined in [RFC8342]. These notifications are designed to support 96 the monitoring of the base system events within the server and not 97 specific to any network management protocols such as NETCONF and 98 RESTCONF. 100 The solution presented in this document is backwards compatible with 101 [RFC6470]. 103 1.1. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 The following terms are defined in [RFC8342] and are not redefined 112 here: 114 o operational state datastore 116 o running configuration datastore 118 o intended configuration datastore 120 2. NMDA Base Notifications for applied intended configuration 122 2.1. Overview 124 The YANG module in NETCONF Base Notifications [RFC6470] specifies the 125 following 5 event notifications for the 'NETCONF' stream to notify a 126 client application that the NETCONF server state has changed: 128 o netconf-config-change 130 o netconf-capability-change 132 o netconf-session-start 134 o netconf-session-end 136 o netconf-confirmed-commit 138 These event notifications used within the 'NETCONF' stream are 139 accessible to clients via the subscription mechanism described in 140 [RFC5277]. 142 This document introduces NMDA specific extension which allows a 143 client to receive 2 notifications for additional common system events 144 as follows: 146 apply-intended-updated: Generated when a server with network 147 management protocol support detects that all or a set of 148 configurations are successfully applied or none of them are 149 applied. Indicates the event and the current state of the 150 intended configuration applying. In addition, NMDA datastore 151 compare [I-D.ietf-netmod-nmda-diff] should be used to check which 152 part of intended configuration data is applied or which part of 153 intended configuration data is not applied. A server MAY report 154 events for non- NETCONF management sessions (such as 155 RESTCONF,gPRC), using the 'session-id' value of zero. 157 The following figure shows event notification sequence defined in 158 this document. 160 +-------------+ +-----------+ 161 | | | | 162 | (ct, rw) |<---+ +--->| (ct, rw) | 163 +-------------+ | | +-----------+ 164 | | | | 165 | +-----------+ | 166 +-------->| |<--------+ 167 | (ct, rw) | 168 +-----------+ 169 | 170 | // configuration transformations, 171 | // e.g., removal of nodes marked as 172 | // "inactive", expansion of 173 | // templates 174 v 175 +------------+ 176 | | // subject to validation 177 | (ct, ro) | 178 +------------+ 179 | // changes applied, subject to 180 (a)apply-intended-updated | // local factors,e.g., missing 181 | // resources, delays 182 | 183 dynamic | +-------- learned configuration 184 configuration | +-------- system configuration 185 datastores -----+ | +-------- default configuration 186 | | | 187 v v v 188 +---------------+ 189 | | <-- system state 190 | (ct + cf, ro) | 191 +---------------+ 193 ct = config true; cf = config false 194 rw = read-write; ro = read-only 195 boxes denote named datastores 197 These notification messages are accessible to clients via either the 198 subscription mechanism described in [RFC5277] or dynamic subscription 199 mechanism and configured subscription mechanism described in [I- 200 D.ietf-netconf-netconf-event-notifications]. 202 2.2. Data Model Design 204 The data model is defined in the ietf-nmda-notifications YANG module. 205 Its structure is shown in the following figure. The notation syntax 206 follows [RFC8340]. 208 notifications: 209 +---n apply-intended-updated 210 +--ro username string 211 +--ro session-id session-id-or-zero-type 212 +--ro app-tag? tags:tag 213 +--ro source-host? inet:ip-address 214 +--ro commit-persist-id? string 215 +--ro datastore? identityref 216 +--ro (filter-spec)? 217 | +--:(subtree-filter) 218 | | +--ro subtree-filter? 219 | +--:(xpath-filter) 220 | +--ro xpath-filter? yang:xpath1.0 {nc:xpath}? 221 +--ro apply-result? enumeration 222 +--ro fail-applied-target* [edit-id] 223 +--ro edit-id string 224 +--ro operation enumeration 225 +--ro target? ypatch:target-resource-offset 226 +--ro value? 227 +--ro errors 228 +--ro error* [] 229 +--ro error-type enumeration 230 +--ro error-tag string 231 +--ro error-app-tag? string 232 +--ro error-path? instance-identifier 233 +--ro error-message? string 234 +--ro error-info? 236 The following are examples of a apply-intended-updated notification 237 message: 239 240 2017-06-16T16:30:59.137045+09:00 241 242 admin 243 0 244 user:app1 245 10.251.93.83 246 IQ,d4668 247 fail 248 operational 249 250 1 251 merge 252 /ietf-interfaces:interfaces-state 253 254 255 256 eth0 257 down 258 259 260 261 262 263 2 264 /ietf-system:system 265 266 protocol 267 mis-resource 268 \ 269 \/if:interfaces-state\ 270 \ 271 refer to resources that are not \ 272 \available or otherwise not physically present.\ 273 \ 274 275 276 277 279 2.3. Relation with NMDA Datastore Compare 281 NMDA datastore compare [NMDA-DIFF]could be used to check which part 282 of intended configuration data is applied or which part of intended 283 configuration data is not applied. On the other hand, the event 284 notification for apply-intended-start or netconf-confirmed-commit can 285 be used to trigger NMDA datastore compare procedure to be started. 287 2.4. Definitions 289 This section presents the YANG module defined in this document. This 290 module imports data types from the 'ietf-datastores' module defined 291 in [RFC8342] and 'ietf-inet-types' module defined in [RFC6021]. 293 file "ietf-nmda-notifications@2018-12-26.yang" 294 module ietf-nmda-notifications { 295 yang-version 1.1; 296 namespace "urn:ietf:params:xml:ns:yang:ietf-nmda-notifications"; 297 prefix ndn; 298 import ietf-datastores { 299 prefix ds; 300 } 301 import ietf-inet-types { prefix inet; } 302 import ietf-module-tags { prefix tags;} 303 import ietf-yang-types { prefix yang;} 304 import ietf-yang-patch { 305 prefix ypatch; 306 } 307 import ietf-netconf { 308 prefix nc; 309 } 310 import ietf-restconf { prefix rc;} 311 organization 312 "IETF NETMOD (Network Modeling) Working Group"; 313 contact 314 "WG Web: 315 WG List: 316 WG Chair: Kent Watsen 317 318 Editor: Qin Wu 319 320 Editor: Rohit R Ranade 321 "; 322 description 323 "This module defines a YANG data model for use with the 324 NETCONF and RESTCONF protocol that allows the client to 325 receive additional common event notifications related to NMDA. 327 Copyright (c) 2012 IETF Trust and the persons identified as 328 the document authors. All rights reserved. 329 Redistribution and use in source and binary forms, with or 330 without modification, is permitted pursuant to, and subject 331 to the license terms contained in, the Simplified BSD License 332 set forth in Section 4.c of the IETF Trust's Legal Provisions 333 Relating to IETF Documents 334 (http://trustee.ietf.org/license-info). 335 This version of this YANG module is part of RFC xxxx; see 336 the RFC itself for full legal notices."; 338 revision 2018-12-26 { 339 description 340 "Initial version."; 341 reference "RFC xxx: NETCONF Base Notifications for NMDA"; 342 } 343 typedef session-id-or-zero-type { 344 type uint32; 345 description 346 "NETCONF Session Id or Zero to indicate none"; 347 } 348 feature error-info { 349 description 350 "This feature must 351 also be enabled for that session if error-info 352 can be advertised by the server. Otherwise, 353 this feature must not be enabled."; 354 } 355 grouping common-session-parms { 356 description 357 "Common session parameters to identify a 358 management session."; 360 leaf username { 361 type string; 362 mandatory true; 363 description 364 "Name of the user for the session."; 365 } 367 leaf session-id { 368 type session-id-or-zero-type; 369 mandatory true; 370 description 371 "Identifier of the session. 372 A NETCONF session MUST be identified by a non-zero value. 373 A non-NETCONF session MAY be identified by the value zero."; 374 } 376 leaf app-tag { 377 type tags:tag; 378 description 379 "The relationship between username and application tag 380 can be one to many."; 381 } 382 leaf source-host { 383 type inet:ip-address; 384 description 385 "Address of the remote host for the session."; 386 } 388 leaf commit-persist-id { 389 type string; 390 description 391 "This parameter is used to identify each commit. 392 The value of this parameter is a token that must be given 393 in the 'persist-id' parameter of or 394 operations in order to confirm or cancel 395 the persistent confirmed commit. 397 The token should be a random string."; 398 reference "RFC 6241, Section 8.3.4.1"; 399 } 400 } 402 notification apply-intended-updated { 403 description 404 "Generated when a server detects that a 405 intended configuration applied event has occurred. Indicates 406 the event and the current state of the intended data applying 407 procedure in progress."; 408 reference "RFC 8342, Section 5"; 409 uses common-session-parms; 410 leaf datastore { 411 type identityref { 412 base ds:datastore; 413 } 414 default "ds:operational"; 415 description 416 "Indicates which datastore has changed or which datastore is 417 target of edit-data operation."; 418 } 419 choice filter-spec { 420 description 421 "The content filter specification for this request."; 422 anydata subtree-filter { 423 description 424 "This parameter identifies the portions of the 425 target datastore to retrieve."; 426 reference 427 "RFC 6241: Network Configuration Protocol, Section 6."; 428 } 429 leaf xpath-filter { 430 if-feature nc:xpath; 431 type yang:xpath1.0; 432 description 433 "This parameter contains an XPath expression identifying 434 the portions of the target datastore to retrieve. 436 If the expression returns a node-set, all nodes in the 437 node-set are selected by the filter. Otherwise, if the 438 expression does not return a node-set, then the get-data 439 operation fails. 441 The expression is evaluated in the following XPath 442 context: 444 o The set of namespace declarations are those in 445 scope on the 'xpath-filter' leaf element. 447 o The set of variable bindings is empty. 449 o The function library is the core function library, 450 and the XPath functions defined in section 10 in 451 RFC 7950. 453 o The context node is the root node of the target 454 datastore."; 455 } 456 } 457 leaf apply-result { 458 type enumeration { 459 enum "ok" { 460 description 461 "The intended data is succesfully applied."; 462 } 463 enum "fail" { 464 description 465 " The intended data is not succesfully applied."; 466 } 467 } 468 description 469 "Apply result."; 470 } 471 list fail-applied-target { 472 when "../apply-result = 'fail'"; 473 key edit-id; 474 ordered-by user; 475 leaf edit-id { 476 type string; 477 description 478 "Response status is for the 'edit' list entry 479 with this 'edit-id' value."; 480 } 481 leaf operation { 482 type enumeration { 483 enum create { 484 description 485 "The target data node is created using the supplied 486 value, only if it does not already exist. The 487 'target' leaf identifies the data node to be 488 created, not the parent data node."; 489 } 490 enum delete { 491 description 492 "Delete the target node, only if the data resource 493 currently exists; otherwise, return an error."; 494 } 496 enum insert { 497 description 498 "Insert the supplied value into a user-ordered 499 list or leaf-list entry. The target node must 500 represent a new data resource. If the 'where' 501 parameter is set to 'before' or 'after', then 502 the 'point' parameter identifies the insertion 503 point for the target node."; 504 } 505 enum merge { 506 description 507 "The supplied value is merged with the target data 508 node."; 509 } 510 enum move { 511 description 512 "Move the target node. Reorder a user-ordered 513 list or leaf-list. The target node must represent 514 an existing data resource. If the 'where' parameter 515 is set to 'before' or 'after', then the 'point' 516 parameter identifies the insertion point to move 517 the target node."; 518 } 519 enum replace { 520 description 521 "The supplied value is used to replace the target 522 data node."; 523 } 524 enum remove { 525 description 526 "Delete the target node if it currently exists."; 527 } 528 } 529 mandatory true; 530 description 531 "The datastore operation requested for the associated 532 'edit' entry."; 533 } 534 leaf target { 535 type ypatch:target-resource-offset; 536 description 537 "Topmost node associated with the configuration change. 538 A server SHOULD set this object to the node within 539 the datastore that is being altered. A server MAY 540 set this object to one of the ancestors of the actual 541 node that was changed, or omit this object, if the 542 exact node is not known."; 543 } 544 anydata value { 545 description 546 "Value used for this edit operation. The anydata 'value' 547 contains the target resource associated with the 548 'target' leaf. 550 For example, suppose the target node is a YANG container 551 named foo: 553 container foo { 554 leaf a { type string; } 555 leaf b { type int32; } 556 } 558 The 'value' node contains one instance of foo: 560 561 562 some value 563 42 564 565 566 "; 567 } 568 uses rc:errors {if-feature error-info;} 569 description 570 "List for fail applied targets. The fail applied targets 571 are only applied when the intended data is not applied."; 572 } 573 } 575 } 576 578 3. Security Considerations 580 The YANG module defined in this memo is designed to be accessed via 581 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 582 secure transport layer and the mandatory-to-implement secure 583 transport is SSH, defined in [RFC6242]. 585 Some of the readable data nodes in this YANG module may be considered 586 sensitive or vulnerable in some network environments. It is thus 587 important to control read access (e.g., via get, get-config, or 588 notification) to these data nodes. These are the subtrees and data 589 nodes and their sensitivity/vulnerability: 591 /apply-intended-updated: 593 Event type itself indicates that a server may be finished applying 594 configuration from intended. This event could alert an attacker 595 that a datastore may have been altered. 597 /apply-intended-updated/apply-result: 599 Indicates the specific applied intended applied event state change 600 that occurred. A value of 'ok' probably indicates that intended 601 data applying procedure has completed. 603 4. IANA Considerations 605 This document registers one XML namespace URN in the 'IETF XML 606 registry', following the format defined in [RFC3688]: 608 URI: urn:ietf:params:xml:ns:yang:ietf-nmda-notifications 610 Registrant Contact: The IESG. 612 XML: N/A, the requested URI is an XML namespace. 614 This document registers one module name in the 'YANG Module Names' 615 registry, defined in [RFC7950]: 617 name: ietf-nmda-notifications 619 prefix: ndn 621 namespace: urn:ietf:params:xml:ns:yang:ietf-nmda-notifications 622 RFC: xxxx 624 5. Acknowledgements 626 Thanks to Juergen Schoenwaelder, Alex Clemm,Carey Timothy and Andy 627 Berman, Sterne Jason to review this draft and Thank Xiaojian Ding 628 provide important input to the initial version of this document. 630 6. Normative References 632 [I-D.ietf-netmod-nmda-diff] 633 Clemm, A., Qu, Y., Tantsura, J., and A. Bierman, 634 "Comparison of NMDA datastores", draft-ietf-netmod-nmda- 635 diff-00 (work in progress), October 2018. 637 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 638 Requirement Levels", BCP 14, RFC 2119, 639 DOI 10.17487/RFC2119, March 1997, 640 . 642 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 643 DOI 10.17487/RFC3688, January 2004, 644 . 646 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 647 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 648 . 650 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 651 the Network Configuration Protocol (NETCONF)", RFC 6020, 652 DOI 10.17487/RFC6020, October 2010, 653 . 655 [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", 656 RFC 6021, DOI 10.17487/RFC6021, October 2010, 657 . 659 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 660 and A. Bierman, Ed., "Network Configuration Protocol 661 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 662 . 664 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 665 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 666 . 668 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 669 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 670 February 2012, . 672 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 673 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 674 2017, . 676 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 677 and R. Wilton, "Network Management Datastore Architecture 678 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 679 . 681 Appendix A. Changes between revisions 683 v01 - v00 685 o Add module tag support and use additional parameters to identify 686 management session. 688 o Remove apply-intended-start and apply-intended-end two 689 notifications since they are not needed based on discussion. 691 Authors' Addresses 693 Qin Wu 694 Huawei 695 101 Software Avenue, Yuhua District 696 Nanjing, Jiangsu 210012 697 China 699 Email: bill.wu@huawei.com 701 Chong Feng 702 Huawei 704 Email: frank.fengchong@huawei.com 706 Rohit R Ranade 707 Huawei 708 Divyashree Techno Park, Whitefield 709 Bangalore, Karnataka 560066 710 India 712 Email: rohitrranade@huawei.com