idnits 2.17.1 draft-ietf-netconf-system-notifications-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 : ---------------------------------------------------------------------------- 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 (November 15, 2010) is 4882 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 491, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) == Outdated reference: A later version (-10) exists of draft-ietf-netconf-4741bis-06 Summary: 1 error (**), 0 flaws (~~), 3 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 November 15, 2010 5 Expires: May 19, 2011 7 Network Configuration Protocol Notification Events 8 draft-ietf-netconf-system-notifications-02 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 capabilities, which may 15 impact management applications. Standard mechanisms are needed to 16 support the monitoring of the events within the NETCONF server. This 17 document defines a YANG module which allows a NETCONF client to 18 receive notifications for some common events. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 19, 2011. 37 Copyright Notice 39 Copyright (c) 2010 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. YANG Module for Notifications . . . . . . . . . . . . . . . . 3 57 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1.1. Notifications . . . . . . . . . . . . . . . . . . . . 3 59 2.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 62 5. Normative References . . . . . . . . . . . . . . . . . . . . . 11 63 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 12 64 A.1. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 A.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 A.3. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 The NETCONF protocol [I-D.ietf-netconf-4741bis] provides mechanisms 72 to manipulate configuration datastores. However, client applications 73 often need to be aware of common events such as a change in NETCONF 74 capabilities, which may impact management applications. Standard 75 mechanisms are needed to support the monitoring of the events within 76 the NETCONF server. This document defines a YANG module [RFC6020] 77 which allows a NETCONF client to receive notifications for some 78 common events. 80 1.1. Terminology 82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 84 document are to be interpreted as described in [RFC2119]. 86 The following terms are defined in [I-D.ietf-netconf-4741bis]: 87 o client 88 o datastore 89 o operation 90 o server 92 The following terms are defined in [RFC5277]: 93 o event 94 o stream 95 o subscription 97 The following term is defined in [RFC6020]: 98 o data node 100 2. YANG Module for Notifications 102 2.1. Overview 104 The YANG module defined within this document specifies a small number 105 of notification event messages for use within the 'NETCONF' stream, 106 and accessible to clients via the subscription mechanism in 107 [RFC5277]. 109 The YANG language is defined in [RFC6020]. 111 2.1.1. Notifications 113 This module defines some events for the 'NETCONF' stream to notify a 114 client application that the NETCONF server state has changed. 116 o netconf-config-change: Generated when the NETCONF server detects 117 that the or configuration datastore has 118 changed. Summarizes each edit being reported. 119 o netconf-capability-change: Generated when the NETCONF server 120 capabilities are changed. Indicates which capabilities have been 121 added, deleted, and/or modified. 122 o netconf-session-start: Generated when a NETCONF session is 123 started. Indicates the identity of the user that started the 124 session. 125 o netconf-session-end: Generated when a NETCONF server detects that 126 a session has terminated. Indicates the identity of the user that 127 owned the session, and why the session was terminated. 128 o netconf-confirmed-commit: Generated when a NETCONF confirmed- 129 commit event occurs. Indicates the current state of the 130 confirmed-commit operation in progress. 132 2.2. Definitions 134 file="ietf-netconf-events@2010-11-15.yang" 136 module ietf-netconf-events { 138 namespace 139 "urn:ietf:params:xml:ns:yang:ietf-netconf-events"; 141 prefix nce; 143 import ietf-inet-types { prefix inet; } 144 import ietf-netconf { prefix nc; } 146 organization 147 "IETF NETCONF (Network Configuration Protocol) Working Group"; 149 contact 150 "WG Web: 151 WG List: 153 WG Chair: Bert Wijnen 154 156 WG Chair: Mehmet Ersue 157 159 Editor: Andy Bierman 160 "; 162 description 163 "This module defines an YANG data model for use with the 164 NETCONF protocol that allows the NETCONF client to 165 receive common events. 167 Copyright (c) 2010 IETF Trust and the persons identified as 168 the document authors. All rights reserved. 170 Redistribution and use in source and binary forms, with or 171 without modification, is permitted pursuant to, and subject 172 to the license terms contained in, the Simplified BSD License 173 set forth in Section 4.c of the IETF Trust's Legal Provisions 174 Relating to IETF Documents 175 (http://trustee.ietf.org/license-info). 177 This version of this YANG module is part of RFC XXXX; see 178 the RFC itself for full legal notices."; 179 // RFC Ed.: replace XXXX with actual RFC number and remove this note 181 // RFC Ed.: remove this note 182 // Note: extracted from 183 // draft-ietf-netconf-system-notifications-02.txt 185 revision 2010-11-15 { 186 description 187 "Initial version."; 188 reference 189 "RFC XXXX: NETCONF Notification Events"; 190 } 191 // RFC Ed.: replace XXXX with actual 192 // RFC number and remove this note 194 grouping common-session-parms { 196 leaf user-name { 197 description 198 "Name of the user for the session."; 199 type string; 200 } 202 leaf session-id { 203 description "Identifier of the session."; 204 type nc:session-id-or-zero-type; 205 mandatory true; 206 } 208 leaf remote-host { 209 description 210 "Address of the remote host for the session."; 211 type inet:ip-address; 212 } 213 } 215 grouping changed-by-parms { 216 container changed-by { 217 description 218 "Indicates who caused this change. 219 If caused by internal action, then the 220 empty leaf 'server' will be present. 221 If caused by a management session, then 222 the name, remote host address, and session ID 223 of the session that made the change will be reported."; 224 choice server-or-user { 225 leaf server { 226 type empty; 227 description 228 "If present, the change was caused 229 by the server."; 230 } 232 case by-user { 233 uses common-session-parms; 234 } 235 } // choice server-or-user 236 } // container changed-by-parms; 237 } 239 notification netconf-config-change { 240 description 241 "Generated when the or configuration 242 database is changed."; 244 uses changed-by-parms; 246 leaf target-database { 247 type enumeration { 248 enum running { 249 description "The running database has changed."; 250 } 251 enum startup { 252 description "The startup database has changed"; 253 } 254 } 255 description 256 "Indicates which configuration database has changed."; 257 default "running"; 258 } 260 list edit { 261 description 262 "An edit record will be present for each distinct 263 edit operation on the target database."; 265 leaf target { 266 type instance-identifier; 267 description 268 "Topmost node associated with the configuration change. 269 A server SHOULD set this object to the node within 270 the database which is being altered. A server MAY 271 set this object to one of the ancestors of the actual 272 node that was changed, or omit this object, if the 273 exact node is not known."; 274 } 276 leaf operation { 277 type nc:edit-operation-type; 278 description 279 "Type of edit operation performed. 280 A server MUST set this object to the NETCONF edit 281 operation performed on the target database."; 282 } 283 } // list edit 284 } // notification netconf-config-change 286 notification netconf-capability-change { 287 description 288 "Generated when a is added, deleted, 289 or modified."; 291 uses changed-by-parms; 293 leaf-list added-capability { 294 type inet:uri; 295 description 296 "List of capabilities that have just been added."; 297 } 299 leaf-list deleted-capability { 300 type inet:uri; 301 description 302 "List of capabilities that have just been deleted."; 303 } 305 leaf-list modified-capability { 306 type inet:uri; 307 description 308 "List of capabilities that have just been modified. 309 A capability is considered to be modified if the 310 base URI for the capability has not changed, but 311 one or more of the parameters encoded at the end of 312 the capability URI has changed."; 313 } 314 } // notification netconf-capability-change 316 notification netconf-session-start { 317 description 318 "Generated when a new NETCONF session is started."; 319 uses common-session-parms; 320 } // notification netconf-session-start 322 notification netconf-session-end { 323 description 324 "Generated when a NETCONF session is terminated."; 326 uses common-session-parms; 328 leaf killed-by { 329 when "../termination-reason = 'killed'"; 330 type nc:session-id-type; 331 description 332 "Session ID that issued the 333 if the session was terminated by this operation."; 334 } 336 leaf termination-reason { 337 type enumeration { 338 enum "closed" { 339 value 0; 340 description 341 "The session was terminated with 342 the NETCONF operation."; 343 } 344 enum "killed" { 345 value 1; 346 description 347 "The session was terminated with 348 the NETCONF operation."; 349 } 350 enum "dropped" { 351 value 2; 352 description 353 "The session was terminated because 354 the transport layer connection was 355 unexpectedly closed."; 356 } 357 enum "timeout" { 358 value 3; 359 description 360 "The session was terminated because 361 of inactivity, either waiting for 362 the or messages."; 363 } 364 enum "bad-hello" { 365 value 4; 366 description 367 "The client's message was invalid."; 368 } 369 enum "other" { 370 value 5; 371 description 372 "The session was terminated for 373 some other reason."; 374 } 375 } 376 mandatory "true"; 377 description "Reason the session was terminated."; 378 } 379 } // notification netconf-session-end 381 notification netconf-confirmed-commit { 382 description 383 "Generated when a confirmed-commit event occurs."; 384 reference 385 "I-D draft-ietf-netconf-4741bis section 8.4"; 387 uses common-session-parms { 388 refine session-id { 389 mandatory false; 390 } 391 } 393 leaf confirm-event { 394 description 395 "Indicates the event that caused the notification."; 396 type enumeration { 397 enum "start" { 398 value 0; 399 description 400 "The confirm-commit procedure has started."; 401 } 402 enum "cancel" { 403 value 1; 404 description 405 "The confirm-commit procedure has been canceled, 406 due to the session being terminated, or an 407 explicit operation."; 408 } 409 enum "timeout" { 410 value 2; 411 description 412 "The confirm-commit procedure has been canceled, 413 due to the confirm-timeout interval expiring. 414 The common session parameters will not be present 415 in this sub-mode."; 416 } 417 enum "extend" { 418 value 3; 419 description 420 "The confirm-commit timeout has been extended."; 421 } 422 enum "complete" { 423 value 4; 424 description 425 "The confirm-commit procedure has been completed."; 426 } 427 } 428 mandatory "true"; 429 } 431 leaf timeout { 432 when 433 "../confirm-event = 'start' or ../confirm-event = 'extend'"; 434 description 435 "The configured timeout value if the event type 436 is 'start' or 'extend'. This value represents the 437 the approximate number of seconds from the event 438 time when the 'timeout' event might occur."; 439 units "seconds"; 440 type uint32; 441 } 442 } // notification netconf-confirmed-commit 444 } 446 448 3. IANA Considerations 450 This document registers one XML namespace URN in the 'IETF XML 451 registry', following the format defined in [RFC3688]. 453 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-events 455 Registrant Contact: The NETCONF WG of the IETF. 457 XML: N/A, the requested URI is an XML namespace. 459 This document registers one module name in the 'YANG Module Names' 460 registry, defined in [RFC6020] . 462 name: ietf-netconf-events 463 prefix: nce 464 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-events 465 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 467 4. Security Considerations 469 This document defines a YANG module for reporting of particular 470 system events. Although unlikely, it is possible that data obtained 471 from this module could be used in an attack of some kind, although no 472 specific information in this module is considered sensitive. 474 TBD: follow Security Consideration guidelines from new template text. 476 5. Normative References 478 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 479 Requirement Levels", BCP 14, RFC 2119, March 1997. 481 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 482 January 2004. 484 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 485 Notifications", RFC 5277, July 2008. 487 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 488 Network Configuration Protocol (NETCONF)", RFC 6020, 489 October 2010. 491 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 492 October 2010. 494 [I-D.ietf-netconf-4741bis] 495 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 496 Bierman, "Network Configuration Protocol (NETCONF)", 497 draft-ietf-netconf-4741bis-06 (work in progress), 498 October 2010. 500 Appendix A. Change Log 502 -- RFC Ed.: remove this section before publication. 504 A.1. 01-02 506 Renamed module NETCONF Events instead of NETCONF system 507 notifications. Note that ietf-netconf-notfications is being reserved 508 for the XML content defined in RFC 5277. 510 Made changes based on mailing list comments and latest WG consensus. 512 Filled in IANA section. 514 A.2. 00-01 516 Removed sys-startup notification. 518 Make changed-by into a grouping, and added usage to sys-config-change 519 notification. 521 Added target-database leaf to sys-config-change to distinguish 522 between running and startup changes. 524 Removed 'bad-start' from termination-reason leaf in sys-session-end 525 notification. 527 A.3. 00 529 Initial version, based on 530 draft-bierman-netconf-system-monitoring-00.txt. 532 Author's Address 534 Andy Bierman 535 Brocade 537 Email: andy.bierman@brocade.com