idnits 2.17.1 draft-ietf-netconf-system-notifications-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 13, 2011) is 4673 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: 'RFC4741' is mentioned on line 526, but not defined ** Obsolete undefined reference: RFC 4741 (Obsoleted by RFC 6241) == Missing Reference: 'RFC4742' is mentioned on line 528, but not defined ** Obsolete undefined reference: RFC 4742 (Obsoleted by RFC 6242) == Unused Reference: 'RFC6021' is defined on line 630, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Bierman 3 Internet-Draft Brocade 4 Intended status: Standards Track June 13, 2011 5 Expires: December 15, 2011 7 Network Configuration Protocol Base Notifications 8 draft-ietf-netconf-system-notifications-04 10 Abstract 12 The NETCONF protocol provides mechanisms to manipulate configuration 13 datastores. However, client applications often need to be aware of 14 common events such as a change in NETCONF server capabilities, that 15 may impact management applications. Standard mechanisms are needed 16 to support the monitoring of the base system events within the 17 NETCONF server. This document defines a YANG module that allows a 18 NETCONF client to receive notifications for some common system 19 events. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 15, 2011. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. YANG Module for NETCONF Base Notifications . . . . . . . . . . 3 58 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1.1. Notifications . . . . . . . . . . . . . . . . . . . . 4 60 2.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 64 6. Normative References . . . . . . . . . . . . . . . . . . . . . 14 65 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15 66 A.1. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 67 A.2. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 A.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 69 A.4. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 A.5. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 1. Introduction 75 The NETCONF protocol [I-D.ietf-netconf-4741bis] provides mechanisms 76 to manipulate configuration datastores. However, client applications 77 often need to be aware of common events such as a change in NETCONF 78 server capabilities, that may impact management applications. 79 Standard mechanisms are needed to support the monitoring of the base 80 system events within the NETCONF server. This document defines a 81 YANG module [RFC6020] that allows a NETCONF client to receive 82 notifications for some common system events. 84 1.1. Terminology 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in [RFC2119]. 90 The following terms are defined in [I-D.ietf-netconf-4741bis]: 91 o client 92 o datastore 93 o operation 94 o server 96 The following terms are defined in [RFC5277]: 97 o event 98 o stream 99 o subscription 101 The following term is defined in [RFC6020]: 102 o data node 104 2. YANG Module for NETCONF Base Notifications 106 2.1. Overview 108 The YANG module defined within this document specifies a small number 109 of notification event messages for use within the 'NETCONF' stream, 110 and accessible to clients via the subscription mechanism in 111 [RFC5277]. 113 These notifications pertain to configuration and monitoring portion 114 of the managed system, not the entire system. A server MUST report 115 events that are directly related to the NETCONF protocol. A server 116 MAY report events for non-NETCONF management sessions, using the 117 'session-id' value of zero. 119 The YANG language is defined in [RFC6020]. 121 2.1.1. Notifications 123 This module defines some events for the 'NETCONF' stream to notify a 124 client application that the NETCONF server state has changed. 125 netconf-config-change: 126 Generated when the NETCONF server detects that the or 127 configuration datastore has changed. Summarizes each 128 edit being reported. 129 netconf-capability-change: 130 Generated when the NETCONF server detects that the server 131 capabilities have changed. Indicates which capabilities have been 132 added, deleted, and/or modified. 133 netconf-session-start: 134 Generated when a NETCONF server detects that a NETCONF session has 135 started. A server MAY generate this event for non-NETCONF 136 management sessions. Indicates the identity of the user that 137 started the session. 138 netconf-session-end: 139 Generated when a NETCONF server detects that a NETCONF session has 140 terminated. A server MAY optionally generate this event for non- 141 NETCONF management sessions. Indicates the identity of the user 142 that owned the session, and why the session was terminated. 143 netconf-confirmed-commit: 144 Generated when a NETCONF server detects that a confirmed-commit 145 event has occurred. Indicates the event and the current state of 146 the confirmed-commit operation in progress. 148 2.2. Definitions 150 file="ietf-netconf-base-notifications@2011-06-13.yang" 152 module ietf-netconf-base-notifications { 154 namespace 155 "urn:ietf:params:xml:ns:yang:ietf-netconf-base-notifications"; 157 prefix ncbase; 159 import ietf-inet-types { prefix inet; } 160 import ietf-netconf { prefix nc; } 162 organization 163 "IETF NETCONF (Network Configuration Protocol) Working Group"; 165 contact 166 "WG Web: 167 WG List: 169 WG Chair: Bert Wijnen 170 172 WG Chair: Mehmet Ersue 173 175 Editor: Andy Bierman 176 "; 178 description 179 "This module defines an YANG data model for use with the 180 NETCONF protocol that allows the NETCONF client to 181 receive common NETCONF base notification events. 183 Copyright (c) 2011 IETF Trust and the persons identified as 184 the document authors. All rights reserved. 186 Redistribution and use in source and binary forms, with or 187 without modification, is permitted pursuant to, and subject 188 to the license terms contained in, the Simplified BSD License 189 set forth in Section 4.c of the IETF Trust's Legal Provisions 190 Relating to IETF Documents 191 (http://trustee.ietf.org/license-info). 193 This version of this YANG module is part of RFC XXXX; see 194 the RFC itself for full legal notices."; 195 // RFC Ed.: replace XXXX with actual RFC number and remove this note 197 // RFC Ed.: remove this note 198 // Note: extracted from 199 // draft-ietf-netconf-system-notifications-04.txt 201 revision 2011-06-13 { 202 description 203 "Initial version."; 204 reference 205 "RFC XXXX: NETCONF Base Notifications"; 206 } 207 // RFC Ed.: replace XXXX with actual 208 // RFC number and remove this note 210 grouping common-session-parms { 211 description 212 "Common session parameters to identity a 213 management session."; 215 leaf username { 216 description 217 "Name of the user for the session."; 218 type string; 219 mandatory true; 220 } 222 leaf session-id { 223 description 224 "Identifier of the session. 225 A non-NETCONF session will be identified by the value zero."; 226 type nc:session-id-or-zero-type; 227 mandatory true; 228 } 230 leaf source-host { 231 description 232 "Address of the remote host for the session."; 233 type inet:ip-address; 234 } 235 } 237 grouping changed-by-parms { 238 description 239 "Common parameters to identify the source 240 of a change event, such as a configuration 241 or capability change."; 243 container changed-by { 244 description 245 "Indicates the source of the change. 246 If caused by internal action, then the 247 empty leaf 'server' will be present. 248 If caused by a management session, then 249 the name, remote host address, and session ID 250 of the session that made the change will be reported."; 251 choice server-or-user { 252 mandatory true; 253 leaf server { 254 type empty; 255 description 256 "If present, the change was caused 257 by the server."; 258 } 260 case by-user { 261 uses common-session-parms; 263 } 264 } // choice server-or-user 265 } // container changed-by-parms; 266 } 268 notification netconf-config-change { 269 description 270 "Generated when the NETCONF server detects that the 271 or configuration datastore 272 has changed by a management session. 273 Summarizes each edit being reported. 274 The server MAY choose to also generate this 275 notification while loading a datastore during the 276 boot process for the device."; 278 uses changed-by-parms; 280 leaf target-datastore { 281 type enumeration { 282 enum running { 283 description "The datastore has changed."; 284 } 285 enum startup { 286 description "The datastore has changed"; 287 } 288 } 289 description 290 "Indicates which configuration datastore has changed."; 291 default "running"; 292 } 294 list edit { 295 description 296 "An edit record SHOULD be present for each distinct 297 edit operation that the server has detected on 298 the target datastore. This list MAY be omitted 299 if the detailed edit operations are not known. 300 The server MAY report entries in this list for 301 changes not made by a NETCONF session (e.g., CLI)."; 303 leaf target { 304 type instance-identifier; 305 description 306 "Topmost node associated with the configuration change. 307 A server SHOULD set this object to the node within 308 the datastore that is being altered. A server MAY 309 set this object to one of the ancestors of the actual 310 node that was changed, or omit this object, if the 311 exact node is not known."; 312 } 314 leaf operation { 315 type nc:edit-operation-type; 316 description 317 "Type of edit operation performed. 318 A server MUST set this object to the NETCONF edit 319 operation performed on the target datastore."; 320 } 321 } // list edit 322 } // notification netconf-config-change 324 notification netconf-capability-change { 325 description 326 "Generated when the NETCONF server detects that 327 the server capabilities have changed. 328 Indicates which capabilities have been added, deleted, 329 and/or modified."; 331 uses changed-by-parms; 333 leaf-list added-capability { 334 type inet:uri; 335 description 336 "List of capabilities that have just been added."; 337 } 339 leaf-list deleted-capability { 340 type inet:uri; 341 description 342 "List of capabilities that have just been deleted."; 343 } 345 leaf-list modified-capability { 346 type inet:uri; 347 description 348 "List of capabilities that have just been modified. 349 A capability is considered to be modified if the 350 base URI for the capability has not changed, but 351 one or more of the parameters encoded at the end of 352 the capability URI has changed. 353 The new modified value of the complete URI is returned."; 354 } 355 } // notification netconf-capability-change 356 notification netconf-session-start { 357 description 358 "Generated when a NETCONF server detects that a 359 NETCONF session has started. A server MAY generate 360 this event for non-NETCONF management sessions. 361 Indicates the identity of the user that started 362 the session."; 363 uses common-session-parms; 364 } // notification netconf-session-start 366 notification netconf-session-end { 367 description 368 "Generated when a NETCONF server detects that a 369 NETCONF session has terminated. 370 A server MAY optionally generate this event for 371 non-NETCONF management sessions. Indicates the 372 identity of the user that owned the session, 373 and why the session was terminated."; 375 uses common-session-parms; 377 leaf killed-by { 378 when "../termination-reason = 'killed'"; 379 type nc:session-id-type; 380 description 381 "The session ID that issued the , 382 if the session was terminated by this operation. 383 If the session was abnormally terminated by a 384 non-NETCONF client operation, the value '0' will be 385 used instead."; 386 } 388 leaf termination-reason { 389 type enumeration { 390 enum "closed" { 391 value 0; 392 description 393 "The session was terminated by the client in normal 394 fashion, e.g., by the NETCONF 395 operation."; 396 } 397 enum "killed" { 398 value 1; 399 description 400 "The session was terminated by the client in abnormal 401 fashion, e.g., by the NETCONF 402 operation."; 404 } 405 enum "dropped" { 406 value 2; 407 description 408 "The session was terminated because the transport layer 409 connection was unexpectedly closed."; 410 } 411 enum "timeout" { 412 value 3; 413 description 414 "The session was terminated because of inactivity, 415 e.g., waiting for the message or 416 messages."; 417 } 418 enum "bad-hello" { 419 value 4; 420 description 421 "The client's message was invalid."; 422 } 423 enum "other" { 424 value 5; 425 description 426 "The session was terminated for some other reason."; 427 } 428 } 429 mandatory true; 430 description 431 "Reason the session was terminated."; 432 } 433 } // notification netconf-session-end 435 notification netconf-confirmed-commit { 436 description 437 "Generated when a NETCONF server detects that a confirmed-commit 438 event has occurred. Indicates the event and the current state 439 of the confirmed-commit operation in progress."; 440 reference 441 "I-D draft-ietf-netconf-4741bis section 8.4"; 443 uses common-session-parms { 444 when "../confirm-event != 'timeout'"; 445 } 447 leaf confirm-event { 448 description 449 "Indicates the event that caused the notification."; 450 type enumeration { 451 enum "start" { 452 value 0; 453 description 454 "The confirmed-commit procedure has started."; 455 } 456 enum "cancel" { 457 value 1; 458 description 459 "The confirmed-commit procedure has been canceled, 460 e.g., due to the session being terminated, or an 461 explicit operation."; 462 } 463 enum "timeout" { 464 value 2; 465 description 466 "The confirmed-commit procedure has been canceled, 467 due to the confirm-timeout interval expiring. 468 The common session parameters will not be present 469 in this sub-mode."; 470 } 471 enum "extend" { 472 value 3; 473 description 474 "The confirmed-commit timeout has been extended, 475 e.g., by a new operation."; 476 } 477 enum "complete" { 478 value 4; 479 description 480 "The confirmed-commit procedure has been completed."; 481 } 482 } 483 mandatory true; 484 } 486 leaf timeout { 487 when 488 "../confirm-event = 'start' or ../confirm-event = 'extend'"; 489 description 490 "The configured timeout value if the event type 491 is 'start' or 'extend'. This value represents the 492 the approximate number of seconds from the event 493 time when the 'timeout' event might occur."; 494 units "seconds"; 495 type uint32; 496 } 497 } // notification netconf-confirmed-commit 499 } 501 503 3. IANA Considerations 505 This document registers one XML namespace URN in the 'IETF XML 506 registry', following the format defined in [RFC3688]. 508 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-base-notifications 510 Registrant Contact: The NETCONF WG of the IETF. 512 XML: N/A, the requested URI is an XML namespace. 514 This document registers one module name in the 'YANG Module Names' 515 registry, defined in [RFC6020] . 517 name: ietf-netconf-base-notifications 518 prefix: ncbase 519 namespace: 520 urn:ietf:params:xml:ns:yang:ietf-netconf-base-notifications 521 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 523 4. Security Considerations 525 The YANG module defined in this memo is designed to be accessed via 526 the NETCONF protocol [RFC4741]. The lowest NETCONF layer is the 527 secure transport layer and the mandatory-to-implement secure 528 transport is SSH [RFC4742]. 530 Some of the readable data nodes in this YANG module may be considered 531 sensitive or vulnerable in some network environments. It is thus 532 important to control read access (e.g., via , , or 533 ) to these data nodes. These are the subtrees and data 534 nodes and their sensitivity/vulnerability: 536 /netconf-config-change: 537 Event type itself indicates that the system configuration has 538 changed, and may be now be vulnerable to unspecified attacks. 539 /netconf-config-change/changed-by: 540 Indicates whether the server or a specific user management session 541 made the configuration change. Identifies the user name, 542 session-id, and source host address associated with the 543 configuration change, if any. 545 /netconf-config-change/datastore: 546 Indicates which datastore has been changed. This data can be used 547 to determine if the non-volatile startup configuration data has 548 been changed. 549 /netconf-config-change/edit: 550 Identifies the specific edit operations and specific datastore 551 subtree(s) that have changed. This data could be used to 552 determine if specific server vulnerabilities may now be present. 554 /netconf-capability-change: 555 Event type itself indicates that the system capabilities have 556 changed, and may be now be vulnerable to unspecified attacks. 557 /netconf-capability-change/changed-by: 558 Indicates whether the server or a specific user management session 559 made the capability change. Identifies the user name, session-id, 560 and source host address associated with the capability change, if 561 any. 562 /netconf-capability-change/added-capability: 563 Indicates the specific capability URIs that have been added. This 564 data could be used to determine if specific server vulnerabilities 565 may now be present. 566 /netconf-capability-change/deleted-capability: 567 Indicates the specific capability URIs that have been deleted. 568 This data could be used to determine if specific server 569 vulnerabilities may now be present. 570 /netconf-capability-change/modified-capability: 571 Indicates the specific capability URIs that have been modified. 572 This data could be used to determine if specific server 573 vulnerabilities may now be present. 575 /netconf-session-start: 576 Event type itself indicates that a NETCONF or other management 577 session may start altering the device configuration and/or state. 578 /netconf-session-start/username: 579 Indicates the user name associated with the session. 580 /netconf-session-start/source-host: 581 Indicates the source host address associated with the session. 583 /netconf-session-end: 584 Event type itself indicates that a NETCONF or other management 585 session may be finished altering the device configuration and/or 586 state. 587 /netconf-session-end/username: 588 Indicates the user name associated with the session. 590 /netconf-session-end/source-host: 591 Indicates the source host address associated with the session. 593 /netconf-confirmed-commit: 594 Event type itself indicates that the datastore may have 595 changed. 596 /netconf-confirmed-commit/username: 597 Indicates the user name associated with the session. 598 /netconf-confirmed-commit/source-host: 599 Indicates the source host address associated with the session. 600 /netconf-confirmed-commit/confirm-event: 601 Indicates the specific confirmed-commit state change that 602 occurred. A value of 'complete' probably indicates that the 603 datastore has changed. 604 /netconf-confirmed-commit/timeout: 605 Indicates the number of seconds in the future when the 606 datastore may change, due to the server reverting to an older 607 configuration. 609 5. Acknowledgements 611 Thanks to Martin Bjorklund, Juergen Schoenwaelder, Kent Watsen, and 612 many other members of the NETCONF WG for providing important input to 613 this document. 615 6. Normative References 617 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 618 Requirement Levels", BCP 14, RFC 2119, March 1997. 620 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 621 January 2004. 623 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 624 Notifications", RFC 5277, July 2008. 626 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 627 Network Configuration Protocol (NETCONF)", RFC 6020, 628 October 2010. 630 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 631 October 2010. 633 [I-D.ietf-netconf-4741bis] 634 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 635 Bierman, "Network Configuration Protocol (NETCONF)", 636 draft-ietf-netconf-4741bis-10 (work in progress), 637 March 2011. 639 Appendix A. Change Log 641 -- RFC Ed.: remove this section before publication. 643 A.1. 03-04 645 Renamed module to NETCONF Base Notifications. The module is now 646 ietf-netconf-base-notifications. The namespace and prefix are now 647 changed as well. 649 Changed notifications so a server can report non-NETCONF initiated 650 events. 652 Replaced security considerations, according to template in RFC 6087. 654 Added Acknowledgements section. 656 A.2. 02-03 658 Renamed module back to NETCONF system notifications. The module is 659 now ietf-netconf-system-notifications. The namespace and prefix are 660 now changed as well. 662 Leaf user-name is now username, and is now mandatory, to be 663 consistent with netconf monitoring module. 665 Leaf remote-host is now source-host to be consistent with netconf 666 monitoring module. 668 The changed-by choice (server-or-user) is now mandatory. 670 The netconf-config-change description was updated and leaf target- 671 database is now named target-datastore. 673 Term 'database' changed to term 'datastore' in text. 675 netconf-confirmed-commit: changed uses common-session-parms to use 676 when-stmt not refine-stmt. 678 netconf-capability-change: updated description text. 680 A.3. 01-02 682 Renamed module NETCONF Events instead of NETCONF system 683 notifications. Note that ietf-netconf-notifications is being 684 reserved for the XML content defined in RFC 5277. 686 Made changes based on mailing list comments and latest WG consensus. 688 Filled in IANA section. 690 A.4. 00-01 692 Removed sys-startup notification. 694 Make changed-by into a grouping, and added usage to sys-config-change 695 notification. 697 Added target-database leaf to sys-config-change to distinguish 698 between running and startup changes. 700 Removed 'bad-start' from termination-reason leaf in sys-session-end 701 notification. 703 A.5. 00 705 Initial version, based on 706 draft-bierman-netconf-system-monitoring-00.txt. 708 Author's Address 710 Andy Bierman 711 Brocade 713 Email: andy.bierman@brocade.com