idnits 2.17.1 draft-ietf-netconf-system-notifications-01.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 22, 2010) is 4935 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: 'RFC3688' is defined on line 470, but no explicit reference was found in the text == Unused Reference: 'RFC6021' is defined on line 483, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 2 errors (**), 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 October 22, 2010 5 Expires: April 25, 2011 7 NETCONF System Notifications 8 draft-ietf-netconf-system-notifications-01 10 Abstract 12 The NETCONF protocol provides mechanisms to manipulate configuration 13 datastores. However, client applications often need to be aware of 14 common system events such as a change in system capabilities, which 15 may impact management applications. Standard mechanisms are needed 16 to support the monitoring of the system events within the NETCONF 17 server. This document defines a YANG module which allows a NETCONF 18 client to receive notifications for some common system 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 April 25, 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 System 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 . . . . . . . . . . . . . . . . . . . . . 11 64 A.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 A.2. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 1. Introduction 70 The NETCONF protocol [RFC4741] provides mechanisms to manipulate 71 configuration datastores. However, client applications often need to 72 be aware of common system events such as a change in system 73 capabilities, which may impact management applications. Standard 74 mechanisms are needed to support the monitoring of the system events 75 within the NETCONF server. This document defines a YANG module 76 [RFC6020] which allows a NETCONF client to receive notifications for 77 some common system events. 79 1.1. Terminology 81 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 82 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 83 document are to be interpreted as described in [RFC2119]. 85 The following terms are defined in [RFC4741]: 86 o client 87 o datastore 88 o operation 89 o server 91 The following terms are defined in [RFC5277]: 92 o event 93 o stream 94 o subscription 96 The following term is defined in [RFC6020]: 97 o data node 99 2. YANG Module for System Notifications 101 2.1. Overview 103 The YANG module defined within this document specifies a small number 104 of notification event messages for use within the 'NETCONF' stream, 105 and accessible to clients via the subscription mechanism in 106 [RFC5277]. 108 The YANG language is defined in [RFC6020]. 110 2.1.1. Notifications 112 This module defines some system events to notify a client application 113 that the system state has changed. 115 o sys-config-change: Generated when the or 116 configuration datastore is changed. Summarizes each edit being 117 reported. 118 o sys-capability-change: Generated when the NETCONF server 119 capabilities are changed. Indicates which capabilities have been 120 added, deleted, and/or modified. 121 o sys-session-start: Generated when the NETCONF session is started. 122 Indicates the identity of the user that started the session. 123 o sys-session-end: Generated when the NETCONF session is terminated. 124 Indicates the identity of the user that owned the session, and why 125 the session was terminated. 126 o sys-conformed-commit: Generated when the NETCONF confirmed-commit 127 event occurs. Indicates the current state of the confirmed-commit 128 operation in progress. 130 2.2. Definitions 132 file="ietf-netconf-system-notifications@2010-10-21.yang" 134 module ietf-netconf-system-notifications { 136 namespace 137 "urn:ietf:params:xml:ns:yang:ietf-netconf-system-notifications"; 139 prefix nc-sys-notif; 141 import ietf-inet-types { prefix inet; } 142 import ietf-netconf { prefix nc; } 144 organization 145 "IETF NETCONF (Network Configuration Protocol) Working Group"; 147 contact 148 "WG Web: 149 WG List: 151 WG Chair: Bert Wijnen 152 154 WG Chair: Mehmet Ersue 155 157 Editor: Andy Bierman 158 "; 160 description 161 "This module defines an YANG data model for use with the 162 NETCONF protocol that allows the NETCONF client to 163 receive common system events. 165 Copyright (c) 2010 IETF Trust and the persons identified as 166 the document authors. All rights reserved. 168 Redistribution and use in source and binary forms, with or 169 without modification, is permitted pursuant to, and subject 170 to the license terms contained in, the Simplified BSD License 171 set forth in Section 4.c of the IETF Trust's Legal Provisions 172 Relating to IETF Documents 173 (http://trustee.ietf.org/license-info). 175 This version of this YANG module is part of RFC XXXX; see 176 the RFC itself for full legal notices."; 177 // RFC Ed.: replace XXXX with actual RFC number and remove this note 179 // RFC Ed.: remove this note 180 // Note: extracted from 181 // draft-ietf-netconf-system-notifications-01.txt 183 revision 2010-10-21 { 184 description 185 "Initial version."; 186 reference 187 "RFC XXXX: NETCONF System Notifications"; 188 } 189 // RFC Ed.: replace XXXX with actual 190 // RFC number and remove this note 192 grouping sys-common-session-parms { 194 leaf user-name { 195 description 196 "Name of the user for the session."; 197 type string; 198 } 200 leaf session-id { 201 description "Identifier of the session."; 202 type nc:session-id-or-zero-type; 203 } 205 leaf remote-host { 206 description 207 "Address of the remote host for the session."; 208 type inet:ip-address; 210 } 211 } 213 grouping changed-by-parms { 214 container changed-by { 215 description 216 "Indicates who caused this change. 217 If caused by internal action, then the 218 empty leaf 'server' will be present. 219 If caused by a management session, then 220 the name, remote host address, and session ID 221 of the session that made the change will be reported."; 222 choice server-or-user { 223 leaf server { 224 type empty; 225 description 226 "If present, the change was caused 227 by the server."; 228 } 230 case by-user { 231 uses sys-common-session-parms { 232 refine session-id { 233 mandatory true; 234 } 235 } 236 } 237 } // choice server-or-user 238 } // container changed-by-parms; 239 } 241 notification sys-config-change { 242 description 243 "Generated when the or configuration 244 database is changed."; 246 uses changed-by-parms; 248 list edit { 249 description 250 "An edit record will be present for each distinct 251 edit operation on the target database."; 253 leaf target-database { 254 type enumeration { 255 enum running { 256 description "The running database has changed."; 257 } 258 enum startup { 259 description "The startup database has changed"; 260 } 261 } 262 description 263 "Indicates which configuration database has changed."; 264 default "running"; 265 } 267 leaf target { 268 type instance-identifier; 269 description 270 "Topmost node associated with the configuration change. 271 A server SHOULD set this object to the node within 272 the database which is being altered. A server MAY 273 set this object to one of the ancestors of the actual 274 node that was changed, or omit this object, if the 275 exact node is not known."; 276 } 278 leaf operation { 279 type nc:edit-operation-type; 280 description 281 "Type of edit operation performed. 282 A server SHOULD set this object to the NETCONF edit 283 operation performed on the target database."; 284 } 285 } // list edit 286 } // notification sys-config-change 288 notification sys-capability-change { 289 description 290 "Generated when a is added, deleted, 291 or modified."; 293 uses changed-by-parms; 295 leaf-list added-capability { 296 type inet:uri; 297 description 298 "List of capabilities that have just been added."; 299 } 301 leaf-list deleted-capability { 302 type inet:uri; 303 description 304 "List of capabilities that have just been deleted."; 306 } 308 leaf-list modified-capability { 309 type inet:uri; 310 description 311 "List of capabilities that have just been modified. 312 A capability is considered to be modified if the 313 base URI for the capability has not changed, but 314 one or more of the parameters encoded at the end of 315 the capability URI has changed."; 316 } 317 } // notification sys-capability-change 319 notification sys-session-start { 320 description 321 "Generated when a new NETCONF session is started."; 322 uses sys-common-session-parms { 323 refine session-id { 324 mandatory true; 325 } 326 } 327 } // notification sys-session-start 329 notification sys-session-end { 330 description 331 "Generated when a NETCONF session is terminated."; 333 uses sys-common-session-parms { 334 refine session-id { 335 mandatory true; 336 } 337 } 339 leaf killed-by { 340 when "../termination-reason = 'killed'"; 341 type nc:session-id-type; 342 description 343 "Session ID that issued the 344 if the session was terminated by this operation."; 345 } 347 leaf termination-reason { 348 type enumeration { 349 enum "closed" { 350 value 0; 351 description 352 "The session was terminated with 353 the operation."; 354 } 355 enum "killed" { 356 value 1; 357 description 358 "The session was terminated with 359 the NETCONF operation."; 360 } 361 enum "dropped" { 362 value 2; 363 description 364 "The session was terminated because 365 the SSH session or TCP connection was 366 unexpectedly closed."; 367 } 368 enum "timeout" { 369 value 3; 370 description 371 "The session was terminated because 372 of inactivity, either waiting for 373 the or messages."; 374 } 375 enum "bad-hello" { 376 value 4; 377 description 378 "The client's message was 379 bad or never arrived."; 380 } 381 enum "other" { 382 value 5; 383 description 384 "The session was terminated for 385 some other reason."; 386 } 387 } 388 mandatory "true"; 389 description "Reason the session was terminated."; 390 } 391 } // notification sys-session-end 393 notification sys-confirmed-commit { 394 description 395 "Generated when a confirmed-commit event occurs."; 396 uses sys-common-session-parms; 398 leaf confirm-event { 399 description 400 "Indicates the event that caused the notification."; 401 type enumeration { 402 enum "start" { 403 value 0; 404 description 405 "The confirm-commit procedure has started."; 406 } 407 enum "cancel" { 408 value 1; 409 description 410 "The confirm-commit procedure has been canceled, 411 due to the session being terminated."; 412 } 413 enum "timeout" { 414 value 2; 415 description 416 "The confirm-commit procedure has been canceled, 417 due to the confirm-timeout interval expiring. 418 The common session parameters will not be present 419 in this sub-mode."; 420 } 421 enum "extend" { 422 value 3; 423 description 424 "The confirm-commit timeout has been extended."; 425 } 426 enum "complete" { 427 value 4; 428 description 429 "The confirm-commit procedure has been completed."; 430 } 431 } 432 mandatory "true"; 433 } 435 leaf timeout { 436 when 437 "../confirm-event = 'start' or ../confirm-event = 'extend'"; 438 description 439 "The configured timeout value if the event type 440 is 'start' or 'extend'. This value represents the 441 the approximate number of seconds from the event 442 time when the 'timeout' event might occur."; 443 units "seconds"; 444 type uint32; 445 } 446 } // notification sys-confirmed-commit 448 } 450 452 3. IANA Considerations 454 TBD 456 4. Security Considerations 458 This document defines a YANG module for reporting of particular 459 system events. Although unlikely, it is possible that data obtained 460 from this module could be used in an attack of some kind, although no 461 specific information in this module is considered sensitive. 463 TBD: follow Security Consideration guidelines from new template text. 465 5. Normative References 467 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 468 Requirement Levels", BCP 14, RFC 2119, March 1997. 470 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 471 January 2004. 473 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 474 December 2006. 476 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 477 Notifications", RFC 5277, July 2008. 479 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 480 Network Configuration Protocol (NETCONF)", RFC 6020, 481 October 2010. 483 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 484 October 2010. 486 Appendix A. Change Log 488 -- RFC Ed.: remove this section before publication. 490 A.1. 00-01 492 Removed sys-startup notification. 494 Make changed-by into a grouping, and added usage to sys-config-change 495 notification. 497 Added target-database leaf to sys-config-change to distinguish 498 between running and startup changes. 500 Removed 'bad-start' from termination-reason leaf in sys-session-end 501 notification. 503 A.2. 00 505 Initial version, based on 506 draft-bierman-netconf-system-monitoring-00.txt. 508 Author's Address 510 Andy Bierman 511 Brocade 513 Email: andy.bierman@brocade.com