idnits 2.17.1 draft-ietf-netconf-system-notifications-07.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 (December 9, 2011) is 4515 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) ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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 December 9, 2011 5 Expires: June 11, 2012 7 Network Configuration Protocol (NETCONF) Base Notifications 8 draft-ietf-netconf-system-notifications-07 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 June 11, 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. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 A.2. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 67 A.3. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 A.4. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 69 A.5. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 A.6. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 71 A.7. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 17 72 A.8. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 1. Introduction 77 The NETCONF protocol [RFC6241] provides mechanisms to manipulate 78 configuration datastores. However, client applications often need to 79 be aware of common events such as a change in NETCONF server 80 capabilities, that may impact management applications. Standard 81 mechanisms are needed to support the monitoring of the base system 82 events within the NETCONF server. This document defines a YANG 83 module [RFC6020] that allows a NETCONF client to receive 84 notifications for some common system events. 86 1.1. Terminology 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 90 document are to be interpreted as described in [RFC2119]. 92 The following terms are defined in [RFC6241]: 93 o client 94 o datastore 95 o protocol operation 96 o server 98 The following terms are defined in [RFC5277]: 99 o event 100 o stream 101 o subscription 103 The following term is defined in [RFC6020]: 104 o data node 106 2. YANG Module for NETCONF Base Notifications 108 2.1. Overview 110 The YANG module defined within this document specifies a small number 111 of event notification messages for use within the 'NETCONF' stream, 112 and accessible to clients via the subscription mechanism in 113 [RFC5277]. This module imports data types from the 'ietf-netconf' 114 module defined in [RFC6241] and 'ietf-inet-types' module defined in 115 [RFC6021]. 117 These notifications pertain to configuration and monitoring portion 118 of the managed system, not the entire system. A server MUST report 119 events that are directly related to the NETCONF protocol. A server 120 MAY report events for non-NETCONF management sessions, using the 121 'session-id' value of zero. 123 This module defines the following notifications for the 'NETCONF' 124 stream to notify a client application that the NETCONF server state 125 has changed: 127 netconf-config-change: 128 Generated when the NETCONF server detects that the or 129 configuration datastore has changed. Summarizes the 130 edits that have been detected. 131 netconf-capability-change: 132 Generated when the NETCONF server detects that the server 133 capabilities have changed. Indicates which capabilities have been 134 added, deleted, and/or modified. The manner in which a server 135 capability is changed is outside the scope of this document. 136 netconf-session-start: 137 Generated when a NETCONF server detects that a NETCONF session has 138 started. A server MAY generate this event for non-NETCONF 139 management sessions. For example, a CLI-based session could be 140 detected and monitored by the server. Indicates the identity of 141 the user that started the session. 142 netconf-session-end: 143 Generated when a NETCONF server detects that a NETCONF session has 144 terminated. A server MAY optionally generate this event for non- 145 NETCONF management sessions. For example, a CLI-based session 146 could be detected and monitored by the server. Indicates the 147 identity of the user that owned the session, and why the session 148 was terminated. 149 netconf-confirmed-commit: 150 Generated when a NETCONF server detects that a confirmed-commit 151 event has occurred. Indicates the event and the current state of 152 the confirmed-commit procedure in progress. 154 2.2. Definitions 156 file="ietf-netconf-notifications@2011-12-09.yang" 158 module ietf-netconf-notifications { 160 namespace 161 "urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"; 163 prefix ncn; 165 import ietf-inet-types { prefix inet; } 166 import ietf-netconf { prefix nc; } 168 organization 169 "IETF NETCONF (Network Configuration Protocol) Working Group"; 171 contact 172 "WG Web: 173 WG List: 175 WG Chair: Bert Wijnen 176 178 WG Chair: Mehmet Ersue 179 181 Editor: Andy Bierman 182 "; 184 description 185 "This module defines a YANG data model for use with the 186 NETCONF protocol that allows the NETCONF client to 187 receive common NETCONF base event notifications. 189 Copyright (c) 2011 IETF Trust and the persons identified as 190 the document authors. All rights reserved. 192 Redistribution and use in source and binary forms, with or 193 without modification, is permitted pursuant to, and subject 194 to the license terms contained in, the Simplified BSD License 195 set forth in Section 4.c of the IETF Trust's Legal Provisions 196 Relating to IETF Documents 197 (http://trustee.ietf.org/license-info). 199 This version of this YANG module is part of RFC XXXX; see 200 the RFC itself for full legal notices."; 201 // RFC Ed.: replace XXXX with actual RFC number and remove this note 203 // RFC Ed.: remove this note 204 // Note: extracted from 205 // draft-ietf-netconf-system-notifications-07.txt 207 revision "2011-12-09" { 208 description 209 "Initial version."; 210 reference 211 "RFC XXXX: NETCONF Base Notifications"; 212 } 213 // RFC Ed.: replace XXXX with actual 214 // RFC number and remove this note 216 grouping common-session-parms { 217 description 218 "Common session parameters to identify a 219 management session."; 221 leaf username { 222 type string; 223 mandatory true; 224 description 225 "Name of the user for the session."; 226 } 228 leaf session-id { 229 type nc:session-id-or-zero-type; 230 mandatory true; 231 description 232 "Identifier of the session. 233 A NETCONF session MUST be identified by a non-zero value. 234 A non-NETCONF session MAY be identified by the value zero."; 235 } 237 leaf source-host { 238 type inet:ip-address; 239 description 240 "Address of the remote host for the session."; 241 } 242 } 244 grouping changed-by-parms { 245 description 246 "Common parameters to identify the source 247 of a change event, such as a configuration 248 or capability change."; 250 container changed-by { 251 description 252 "Indicates the source of the change. 253 If caused by internal action, then the 254 empty leaf 'server' will be present. 255 If caused by a management session, then 256 the name, remote host address, and session ID 257 of the session that made the change will be reported."; 258 choice server-or-user { 259 mandatory true; 260 leaf server { 261 type empty; 262 description 263 "If present, the change was caused 264 by the server."; 265 } 267 case by-user { 268 uses common-session-parms; 269 } 270 } // choice server-or-user 271 } // container changed-by-parms 272 } 274 notification netconf-config-change { 275 description 276 "Generated when the NETCONF server detects that the 277 or configuration datastore 278 has been changed by a management session. 279 The notification summarizes the edits that 280 have been detected. 282 The server MAY choose to also generate this 283 notification while loading a datastore during the 284 boot process for the device."; 286 uses changed-by-parms; 288 leaf datastore { 289 type enumeration { 290 enum running { 291 description "The datastore has changed."; 292 } 293 enum startup { 294 description "The datastore has changed"; 295 } 296 } 297 default "running"; 298 description 299 "Indicates which configuration datastore has changed."; 300 } 302 list edit { 303 description 304 "An edit record SHOULD be present for each distinct 305 edit operation that the server has detected on 306 the target datastore. This list MAY be omitted 307 if the detailed edit operations are not known. 308 The server MAY report entries in this list for 309 changes not made by a NETCONF session (e.g., CLI)."; 311 leaf target { 312 type instance-identifier; 313 description 314 "Topmost node associated with the configuration change. 315 A server SHOULD set this object to the node within 316 the datastore that is being altered. A server MAY 317 set this object to one of the ancestors of the actual 318 node that was changed, or omit this object, if the 319 exact node is not known."; 320 } 322 leaf operation { 323 type nc:edit-operation-type; 324 description 325 "Type of edit operation performed. 326 A server MUST set this object to the NETCONF edit 327 operation performed on the target datastore."; 328 } 329 } // list edit 330 } // notification netconf-config-change 332 notification netconf-capability-change { 333 description 334 "Generated when the NETCONF server detects that 335 the server capabilities have changed. 336 Indicates which capabilities have been added, deleted, 337 and/or modified. The manner in which a server 338 capability is changed is outside the scope of this 339 document."; 341 uses changed-by-parms; 343 leaf-list added-capability { 344 type inet:uri; 345 description 346 "List of capabilities that have just been added."; 347 } 349 leaf-list deleted-capability { 350 type inet:uri; 351 description 352 "List of capabilities that have just been deleted."; 353 } 355 leaf-list modified-capability { 356 type inet:uri; 357 description 358 "List of capabilities that have just been modified. 359 A capability is considered to be modified if the 360 base URI for the capability has not changed, but 361 one or more of the parameters encoded at the end of 362 the capability URI has changed. 363 The new modified value of the complete URI is returned."; 364 } 365 } // notification netconf-capability-change 367 notification netconf-session-start { 368 description 369 "Generated when a NETCONF server detects that a 370 NETCONF session has started. A server MAY generate 371 this event for non-NETCONF management sessions. 372 Indicates the identity of the user that started 373 the session."; 374 uses common-session-parms; 375 } // notification netconf-session-start 377 notification netconf-session-end { 378 description 379 "Generated when a NETCONF server detects that a 380 NETCONF session has terminated. 381 A server MAY optionally generate this event for 382 non-NETCONF management sessions. Indicates the 383 identity of the user that owned the session, 384 and why the session was terminated."; 386 uses common-session-parms; 388 leaf killed-by { 389 when "../termination-reason = 'killed'"; 390 type nc:session-id-type; 391 description 392 "The ID of the session that directly caused this session 393 to be abnormally terminated. If this session was abnormally 394 terminated by a non-NETCONF session unknown to the server, 395 then this leaf will not be present."; 396 } 398 leaf termination-reason { 399 type enumeration { 400 enum "closed" { 401 description 402 "The session was terminated by the client in normal 403 fashion, e.g., by the NETCONF 404 protocol operation."; 405 } 406 enum "killed" { 407 description 408 "The session was terminated in abnormal 409 fashion, e.g., by the NETCONF 410 protocol operation."; 411 } 412 enum "dropped" { 413 description 414 "The session was terminated because the transport layer 415 connection was unexpectedly closed."; 416 } 417 enum "timeout" { 418 description 419 "The session was terminated because of inactivity, 420 e.g., waiting for the message or 421 messages."; 422 } 423 enum "bad-hello" { 424 description 425 "The client's message was invalid."; 426 } 427 enum "other" { 428 description 429 "The session was terminated for some other reason."; 430 } 431 } 432 mandatory true; 433 description 434 "Reason the session was terminated."; 435 } 436 } // notification netconf-session-end 438 notification netconf-confirmed-commit { 439 description 440 "Generated when a NETCONF server detects that a confirmed-commit 441 event has occurred. Indicates the event and the current state 442 of the confirmed-commit procedure in progress."; 443 reference 444 "RFC 6241, section 8.4"; 446 uses common-session-parms { 447 when "../confirm-event != 'timeout'"; 448 } 450 leaf confirm-event { 451 type enumeration { 452 enum "start" { 453 description 454 "The confirmed-commit procedure has started."; 455 } 456 enum "cancel" { 457 description 458 "The confirmed-commit procedure has been canceled, 459 e.g., due to the session being terminated, or an 460 explicit operation."; 461 } 462 enum "timeout" { 463 description 464 "The confirmed-commit procedure has been canceled, 465 due to the confirm-timeout interval expiring. 466 The common session parameters will not be present 467 in this sub-mode."; 468 } 469 enum "extend" { 470 description 471 "The confirmed-commit timeout has been extended, 472 e.g., by a new operation."; 473 } 474 enum "complete" { 475 description 476 "The confirmed-commit procedure has been completed."; 477 } 478 } 479 mandatory true; 480 description 481 "Indicates the event that caused the notification."; 482 } 484 leaf timeout { 485 when 486 "../confirm-event = 'start' or ../confirm-event = 'extend'"; 487 type uint32; 488 units "seconds"; 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 } 495 } // notification netconf-confirmed-commit 497 } 498 500 3. IANA Considerations 502 This document registers one XML namespace URN in the 'IETF XML 503 registry', following the format defined in [RFC3688]. 505 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications 507 Registrant Contact: The IESG. 509 XML: N/A, the requested URI is an XML namespace. 511 This document registers one module name in the 'YANG Module Names' 512 registry, defined in [RFC6020] . 514 name: ietf-netconf-notifications 515 prefix: ncn 516 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications 517 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 519 4. Security Considerations 521 The YANG module defined in this memo is designed to be accessed via 522 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 523 secure transport layer and the mandatory-to-implement secure 524 transport is SSH, defined in [RFC6242]. 526 Some of the readable data nodes in this YANG module may be considered 527 sensitive or vulnerable in some network environments. It is thus 528 important to control read access (e.g., via , , or 529 ) to these data nodes. These are the subtrees and data 530 nodes and their sensitivity/vulnerability: 532 /netconf-config-change: 533 Event type itself indicates that the system configuration has 534 changed. This event could alert an attacker that specific 535 configuration data nodes have been altered. 536 /netconf-config-change/changed-by: 537 Indicates whether the server or a specific user management session 538 made the configuration change. Identifies the user name, 539 session-id, and source host address associated with the 540 configuration change, if any. 542 /netconf-config-change/datastore: 543 Indicates which datastore has been changed. This data can be used 544 to determine if the non-volatile startup configuration data has 545 been changed. 546 /netconf-config-change/edit: 547 Identifies the specific edit operations and specific datastore 548 subtree(s) that have changed. This data could be used to 549 determine if specific server vulnerabilities may now be present. 551 /netconf-capability-change: 552 Event type itself indicates that the system capabilities have 553 changed, and may be now be vulnerable to unspecified attacks. An 554 attacker will likely need to understand the content represented by 555 specific capability URI strings. For example, knowing that a 556 packet capture monitoring capability has been added to the system 557 might help an attacker identify the device for possible 558 unauthorized eavesdropping. 559 /netconf-capability-change/changed-by: 560 Indicates whether the server or a specific user management session 561 made the capability change. Identifies the user name, session-id, 562 and source host address associated with the capability change, if 563 any. 564 /netconf-capability-change/added-capability: 565 Indicates the specific capability URIs that have been added. This 566 data could be used to determine if specific server vulnerabilities 567 may now be present. 568 /netconf-capability-change/deleted-capability: 569 Indicates the specific capability URIs that have been deleted. 570 This data could be used to determine if specific server 571 vulnerabilities may now be present. 572 /netconf-capability-change/modified-capability: 573 Indicates the specific capability URIs that have been modified. 574 This data could be used to determine if specific server 575 vulnerabilities may now be present. 577 /netconf-session-start: 578 Event type itself indicates that a NETCONF or other management 579 session may start altering the device configuration and/or state. 580 It may be possible for an attacker to alter the configuration, by 581 taking advantage somehow of another session concurrently editing 582 an unlocked datastore. 583 /netconf-session-start/username: 584 Indicates the user name associated with the session. 585 /netconf-session-start/source-host: 586 Indicates the source host address associated with the session. 588 /netconf-session-end: 589 Event type itself indicates that a NETCONF or other management 590 session may be finished altering the device configuration. This 591 event could alert an attacker that a datastore may have been 592 altered. 593 /netconf-session-end/username: 594 Indicates the user name associated with the session. 595 /netconf-session-end/source-host: 596 Indicates the source host address associated with the session. 598 /netconf-confirmed-commit: 599 Event type itself indicates that the datastore may have 600 changed. This event could alert an attacker that the device 601 behavior has changed. 602 /netconf-confirmed-commit/username: 603 Indicates the user name associated with the session. 604 /netconf-confirmed-commit/source-host: 605 Indicates the source host address associated with the session. 606 /netconf-confirmed-commit/confirm-event: 607 Indicates the specific confirmed-commit state change that 608 occurred. A value of 'complete' probably indicates that the 609 datastore has changed. 610 /netconf-confirmed-commit/timeout: 611 Indicates the number of seconds in the future when the 612 datastore may change, due to the server reverting to an older 613 configuration. 615 5. Acknowledgements 617 Thanks to Martin Bjorklund, Juergen Schoenwaelder, Kent Watsen, and 618 many other members of the NETCONF WG for providing important input to 619 this document. 621 6. Normative References 623 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 624 Requirement Levels", BCP 14, RFC 2119, March 1997. 626 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 627 January 2004. 629 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 630 Notifications", RFC 5277, July 2008. 632 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 633 Network Configuration Protocol (NETCONF)", RFC 6020, 634 October 2010. 636 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 637 October 2010. 639 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 640 Bierman, "Network Configuration Protocol (NETCONF)", 641 RFC 6241, June 2011. 643 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 644 Shell (SSH)", RFC 6242, June 2011. 646 Appendix A. Change Log 648 -- RFC Ed.: remove this section before publication. 650 A.1. 06-07 652 Add clarifications resulting from IESG review. 654 Add text mentioning that ietf-netconf and ietf-inet-types are 655 imported to reuse types, to resolve idnits for 'unused reference' 656 error. 658 A.2. 05-06 660 Changed YANG statements to canonical order. 662 Corrected when-stmt for killed-by leaf. 664 Corrected IANA Considerations text. 666 Removed redundant value-stmts from confirm-event leaf. 668 A.3. 04-05 670 The module is now ietf-netconf-notifications. The namespace and 671 prefix are now changed as well. 673 The target-datastore has been renamed to datastore. 675 Clarified behavior for non-NETCONF sessions. 677 Minor editorial comments from WG Last Call. 679 A.4. 03-04 681 Renamed module to NETCONF Base Notifications. The module is now 682 ietf-netconf-base-notifications. The namespace and prefix are now 683 changed as well. 685 Changed notifications so a server can report non-NETCONF initiated 686 events. 688 Replaced security considerations, according to template in RFC 6087. 690 Added Acknowledgements section. 692 A.5. 02-03 694 Renamed module back to NETCONF system notifications. The module is 695 now ietf-netconf-system-notifications. The namespace and prefix are 696 now changed as well. 698 Leaf user-name is now username, and is now mandatory, to be 699 consistent with netconf monitoring module. 701 Leaf remote-host is now source-host to be consistent with netconf 702 monitoring module. 704 The changed-by choice (server-or-user) is now mandatory. 706 The netconf-config-change description was updated and leaf target- 707 database is now named target-datastore. 709 Term 'database' changed to term 'datastore' in text. 711 netconf-confirmed-commit: changed uses common-session-parms to use 712 when-stmt not refine-stmt. 714 netconf-capability-change: updated description text. 716 A.6. 01-02 718 Renamed module NETCONF Events instead of NETCONF system 719 notifications. Note that ietf-netconf-notifications is being 720 reserved for the XML content defined in RFC 5277. 722 Made changes based on mailing list comments and latest WG consensus. 724 Filled in IANA section. 726 A.7. 00-01 728 Removed sys-startup notification. 730 Make changed-by into a grouping, and added usage to sys-config-change 731 notification. 733 Added target-database leaf to sys-config-change to distinguish 734 between running and startup changes. 736 Removed 'bad-start' from termination-reason leaf in sys-session-end 737 notification. 739 A.8. 00 741 Initial version, based on 742 draft-bierman-netconf-system-monitoring-00.txt. 744 Author's Address 746 Andy Bierman 747 Brocade 749 Email: andy.bierman@brocade.com