idnits 2.17.1 draft-ietf-netconf-system-notifications-06.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 (October 28, 2011) is 4565 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) == Unused Reference: 'RFC6021' is defined on line 623, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 1 error (**), 0 flaws (~~), 2 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 October 28, 2011 5 Expires: April 30, 2012 7 Network Configuration Protocol (NETCONF) Base Notifications 8 draft-ietf-netconf-system-notifications-06 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 April 30, 2012. 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.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 62 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 63 6. Normative References . . . . . . . . . . . . . . . . . . . . . 14 64 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15 65 A.1. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 A.2. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 67 A.3. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 A.4. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 69 A.5. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 A.6. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 71 A.7. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 1. Introduction 76 The NETCONF protocol [RFC6241] provides mechanisms to manipulate 77 configuration datastores. However, client applications often need to 78 be aware of common events such as a change in NETCONF server 79 capabilities, that may impact management applications. Standard 80 mechanisms are needed to support the monitoring of the base system 81 events within the NETCONF server. This document defines a YANG 82 module [RFC6020] that allows a NETCONF client to receive 83 notifications for some common system events. 85 1.1. Terminology 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in [RFC2119]. 91 The following terms are defined in [RFC6241]: 92 o client 93 o datastore 94 o protocol operation 95 o server 97 The following terms are defined in [RFC5277]: 98 o event 99 o stream 100 o subscription 102 The following term is defined in [RFC6020]: 103 o data node 105 2. YANG Module for NETCONF Base Notifications 107 2.1. Overview 109 The YANG module defined within this document specifies a small number 110 of event notification messages for use within the 'NETCONF' stream, 111 and accessible to clients via the subscription mechanism in 112 [RFC5277]. 114 These notifications pertain to configuration and monitoring portion 115 of the managed system, not the entire system. A server MUST report 116 events that are directly related to the NETCONF protocol. A server 117 MAY report events for non-NETCONF management sessions, using the 118 'session-id' value of zero. 120 This module defines the following notifications for the 'NETCONF' 121 stream to notify a client application that the NETCONF server state 122 has changed: 124 netconf-config-change: 125 Generated when the NETCONF server detects that the or 126 configuration datastore has changed. Summarizes the 127 edits that have been detected. 128 netconf-capability-change: 129 Generated when the NETCONF server detects that the server 130 capabilities have changed. Indicates which capabilities have been 131 added, deleted, and/or modified. The manner in which a server 132 capability is changed is outside the scope of this document. 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 procedure in progress. 148 2.2. Definitions 150 file="ietf-netconf-notifications@2011-10-28.yang" 152 module ietf-netconf-notifications { 154 namespace 155 "urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"; 157 prefix ncn; 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 a YANG data model for use with the 180 NETCONF protocol that allows the NETCONF client to 181 receive common NETCONF base event notifications. 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-06.txt 201 revision "2011-10-28" { 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 identify a 213 management session."; 215 leaf username { 216 type string; 217 mandatory true; 218 description 219 "Name of the user for the session."; 220 } 222 leaf session-id { 223 type nc:session-id-or-zero-type; 224 mandatory true; 225 description 226 "Identifier of the session. 227 A NETCONF session MUST be identified by a non-zero value. 228 A non-NETCONF session MAY be identified by the value zero."; 229 } 231 leaf source-host { 232 type inet:ip-address; 233 description 234 "Address of the remote host for the session."; 235 } 236 } 238 grouping changed-by-parms { 239 description 240 "Common parameters to identify the source 241 of a change event, such as a configuration 242 or capability change."; 244 container changed-by { 245 description 246 "Indicates the source of the change. 247 If caused by internal action, then the 248 empty leaf 'server' will be present. 249 If caused by a management session, then 250 the name, remote host address, and session ID 251 of the session that made the change will be reported."; 252 choice server-or-user { 253 mandatory true; 254 leaf server { 255 type empty; 256 description 257 "If present, the change was caused 258 by the server."; 259 } 261 case by-user { 262 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 The notification summarizes the edits that 274 have been detected. 276 The server MAY choose to also generate this 277 notification while loading a datastore during the 278 boot process for the device."; 280 uses changed-by-parms; 282 leaf datastore { 283 type enumeration { 284 enum running { 285 description "The datastore has changed."; 286 } 287 enum startup { 288 description "The datastore has changed"; 289 } 290 } 291 default "running"; 292 description 293 "Indicates which configuration datastore has changed."; 294 } 296 list edit { 297 description 298 "An edit record SHOULD be present for each distinct 299 edit operation that the server has detected on 300 the target datastore. This list MAY be omitted 301 if the detailed edit operations are not known. 302 The server MAY report entries in this list for 303 changes not made by a NETCONF session (e.g., CLI)."; 305 leaf target { 306 type instance-identifier; 307 description 308 "Topmost node associated with the configuration change. 310 A server SHOULD set this object to the node within 311 the datastore that is being altered. A server MAY 312 set this object to one of the ancestors of the actual 313 node that was changed, or omit this object, if the 314 exact node is not known."; 315 } 317 leaf operation { 318 type nc:edit-operation-type; 319 description 320 "Type of edit operation performed. 321 A server MUST set this object to the NETCONF edit 322 operation performed on the target datastore."; 323 } 324 } // list edit 325 } // notification netconf-config-change 327 notification netconf-capability-change { 328 description 329 "Generated when the NETCONF server detects that 330 the server capabilities have changed. 331 Indicates which capabilities have been added, deleted, 332 and/or modified. The manner in which a server 333 capability is changed is outside the scope of this 334 document."; 336 uses changed-by-parms; 338 leaf-list added-capability { 339 type inet:uri; 340 description 341 "List of capabilities that have just been added."; 342 } 344 leaf-list deleted-capability { 345 type inet:uri; 346 description 347 "List of capabilities that have just been deleted."; 348 } 350 leaf-list modified-capability { 351 type inet:uri; 352 description 353 "List of capabilities that have just been modified. 354 A capability is considered to be modified if the 355 base URI for the capability has not changed, but 356 one or more of the parameters encoded at the end of 357 the capability URI has changed. 358 The new modified value of the complete URI is returned."; 359 } 360 } // notification netconf-capability-change 362 notification netconf-session-start { 363 description 364 "Generated when a NETCONF server detects that a 365 NETCONF session has started. A server MAY generate 366 this event for non-NETCONF management sessions. 367 Indicates the identity of the user that started 368 the session."; 369 uses common-session-parms; 370 } // notification netconf-session-start 372 notification netconf-session-end { 373 description 374 "Generated when a NETCONF server detects that a 375 NETCONF session has terminated. 376 A server MAY optionally generate this event for 377 non-NETCONF management sessions. Indicates the 378 identity of the user that owned the session, 379 and why the session was terminated."; 381 uses common-session-parms; 383 leaf killed-by { 384 when "../termination-reason = 'killed'"; 385 type nc:session-id-type; 386 description 387 "The ID of the session that directly caused this session 388 to be abnormally terminated. If this session was abnormally 389 terminated by a non-NETCONF session unknown to the server, 390 then this leaf will not be present."; 391 } 393 leaf termination-reason { 394 type enumeration { 395 enum "closed" { 396 description 397 "The session was terminated by the client in normal 398 fashion, e.g., by the NETCONF 399 protocol operation."; 400 } 401 enum "killed" { 402 description 403 "The session was terminated in abnormal 404 fashion, e.g., by the NETCONF 405 protocol operation."; 406 } 407 enum "dropped" { 408 description 409 "The session was terminated because the transport layer 410 connection was unexpectedly closed."; 411 } 412 enum "timeout" { 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 description 420 "The client's message was invalid."; 421 } 422 enum "other" { 423 description 424 "The session was terminated for some other reason."; 425 } 426 } 427 mandatory true; 428 description 429 "Reason the session was terminated."; 430 } 431 } // notification netconf-session-end 433 notification netconf-confirmed-commit { 434 description 435 "Generated when a NETCONF server detects that a confirmed-commit 436 event has occurred. Indicates the event and the current state 437 of the confirmed-commit procedure in progress."; 438 reference 439 "RFC 6241, section 8.4"; 441 uses common-session-parms { 442 when "../confirm-event != 'timeout'"; 443 } 445 leaf confirm-event { 446 type enumeration { 447 enum "start" { 448 description 449 "The confirmed-commit procedure has started."; 451 } 452 enum "cancel" { 453 description 454 "The confirmed-commit procedure has been canceled, 455 e.g., due to the session being terminated, or an 456 explicit operation."; 457 } 458 enum "timeout" { 459 description 460 "The confirmed-commit procedure has been canceled, 461 due to the confirm-timeout interval expiring. 462 The common session parameters will not be present 463 in this sub-mode."; 464 } 465 enum "extend" { 466 description 467 "The confirmed-commit timeout has been extended, 468 e.g., by a new operation."; 469 } 470 enum "complete" { 471 description 472 "The confirmed-commit procedure has been completed."; 473 } 474 } 475 mandatory true; 476 description 477 "Indicates the event that caused the notification."; 478 } 480 leaf timeout { 481 when 482 "../confirm-event = 'start' or ../confirm-event = 'extend'"; 483 type uint32; 484 units "seconds"; 485 description 486 "The configured timeout value if the event type 487 is 'start' or 'extend'. This value represents the 488 the approximate number of seconds from the event 489 time when the 'timeout' event might occur."; 490 } 491 } // notification netconf-confirmed-commit 493 } 495 497 3. IANA Considerations 499 This document registers one XML namespace URN in the 'IETF XML 500 registry', following the format defined in [RFC3688]. 502 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications 504 Registrant Contact: The IESG. 506 XML: N/A, the requested URI is an XML namespace. 508 This document registers one module name in the 'YANG Module Names' 509 registry, defined in [RFC6020] . 511 name: ietf-netconf-notifications 512 prefix: ncn 513 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications 514 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 516 4. Security Considerations 518 The YANG module defined in this memo is designed to be accessed via 519 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 520 secure transport layer and the mandatory-to-implement secure 521 transport is SSH, defined in [RFC6242]. 523 Some of the readable data nodes in this YANG module may be considered 524 sensitive or vulnerable in some network environments. It is thus 525 important to control read access (e.g., via , , or 526 ) to these data nodes. These are the subtrees and data 527 nodes and their sensitivity/vulnerability: 529 /netconf-config-change: 530 Event type itself indicates that the system configuration has 531 changed. 532 /netconf-config-change/changed-by: 533 Indicates whether the server or a specific user management session 534 made the configuration change. Identifies the user name, 535 session-id, and source host address associated with the 536 configuration change, if any. 537 /netconf-config-change/datastore: 538 Indicates which datastore has been changed. This data can be used 539 to determine if the non-volatile startup configuration data has 540 been changed. 542 /netconf-config-change/edit: 543 Identifies the specific edit operations and specific datastore 544 subtree(s) that have changed. This data could be used to 545 determine if specific server vulnerabilities may now be present. 547 /netconf-capability-change: 548 Event type itself indicates that the system capabilities have 549 changed, and may be now be vulnerable to unspecified attacks. 550 /netconf-capability-change/changed-by: 551 Indicates whether the server or a specific user management session 552 made the capability change. Identifies the user name, session-id, 553 and source host address associated with the capability change, if 554 any. 555 /netconf-capability-change/added-capability: 556 Indicates the specific capability URIs that have been added. This 557 data could be used to determine if specific server vulnerabilities 558 may now be present. 559 /netconf-capability-change/deleted-capability: 560 Indicates the specific capability URIs that have been deleted. 561 This data could be used to determine if specific server 562 vulnerabilities may now be present. 563 /netconf-capability-change/modified-capability: 564 Indicates the specific capability URIs that have been modified. 565 This data could be used to determine if specific server 566 vulnerabilities may now be present. 568 /netconf-session-start: 569 Event type itself indicates that a NETCONF or other management 570 session may start altering the device configuration and/or state. 571 /netconf-session-start/username: 572 Indicates the user name associated with the session. 573 /netconf-session-start/source-host: 574 Indicates the source host address associated with the session. 576 /netconf-session-end: 577 Event type itself indicates that a NETCONF or other management 578 session may be finished altering the device configuration and/or 579 state. 580 /netconf-session-end/username: 581 Indicates the user name associated with the session. 582 /netconf-session-end/source-host: 583 Indicates the source host address associated with the session. 585 /netconf-confirmed-commit: 586 Event type itself indicates that the datastore may have 587 changed. 589 /netconf-confirmed-commit/username: 590 Indicates the user name associated with the session. 591 /netconf-confirmed-commit/source-host: 592 Indicates the source host address associated with the session. 593 /netconf-confirmed-commit/confirm-event: 594 Indicates the specific confirmed-commit state change that 595 occurred. A value of 'complete' probably indicates that the 596 datastore has changed. 597 /netconf-confirmed-commit/timeout: 598 Indicates the number of seconds in the future when the 599 datastore may change, due to the server reverting to an older 600 configuration. 602 5. Acknowledgements 604 Thanks to Martin Bjorklund, Juergen Schoenwaelder, Kent Watsen, and 605 many other members of the NETCONF WG for providing important input to 606 this document. 608 6. Normative References 610 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 611 Requirement Levels", BCP 14, RFC 2119, March 1997. 613 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 614 January 2004. 616 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 617 Notifications", RFC 5277, July 2008. 619 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 620 Network Configuration Protocol (NETCONF)", RFC 6020, 621 October 2010. 623 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 624 October 2010. 626 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 627 Bierman, "Network Configuration Protocol (NETCONF)", 628 RFC 6241, June 2011. 630 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 631 Shell (SSH)", RFC 6242, June 2011. 633 Appendix A. Change Log 635 -- RFC Ed.: remove this section before publication. 637 A.1. 05-06 639 Changed YANG statements to canonical order. 641 Corrected when-stmt for killed-by leaf. 643 Corrected IANA Considerations text. 645 Removed redundant value-stmts from confirm-event leaf. 647 A.2. 04-05 649 The module is now ietf-netconf-notifications. The namespace and 650 prefix are now changed as well. 652 The target-datastore has been renamed to datastore. 654 Clarified behavior for non-NETCONF sessions. 656 Minor editorial comments from WG Last Call. 658 A.3. 03-04 660 Renamed module to NETCONF Base Notifications. The module is now 661 ietf-netconf-base-notifications. The namespace and prefix are now 662 changed as well. 664 Changed notifications so a server can report non-NETCONF initiated 665 events. 667 Replaced security considerations, according to template in RFC 6087. 669 Added Acknowledgements section. 671 A.4. 02-03 673 Renamed module back to NETCONF system notifications. The module is 674 now ietf-netconf-system-notifications. The namespace and prefix are 675 now changed as well. 677 Leaf user-name is now username, and is now mandatory, to be 678 consistent with netconf monitoring module. 680 Leaf remote-host is now source-host to be consistent with netconf 681 monitoring module. 683 The changed-by choice (server-or-user) is now mandatory. 685 The netconf-config-change description was updated and leaf target- 686 database is now named target-datastore. 688 Term 'database' changed to term 'datastore' in text. 690 netconf-confirmed-commit: changed uses common-session-parms to use 691 when-stmt not refine-stmt. 693 netconf-capability-change: updated description text. 695 A.5. 01-02 697 Renamed module NETCONF Events instead of NETCONF system 698 notifications. Note that ietf-netconf-notifications is being 699 reserved for the XML content defined in RFC 5277. 701 Made changes based on mailing list comments and latest WG consensus. 703 Filled in IANA section. 705 A.6. 00-01 707 Removed sys-startup notification. 709 Make changed-by into a grouping, and added usage to sys-config-change 710 notification. 712 Added target-database leaf to sys-config-change to distinguish 713 between running and startup changes. 715 Removed 'bad-start' from termination-reason leaf in sys-session-end 716 notification. 718 A.7. 00 720 Initial version, based on 721 draft-bierman-netconf-system-monitoring-00.txt. 723 Author's Address 725 Andy Bierman 726 Brocade 728 Email: andy.bierman@brocade.com