idnits 2.17.1 draft-ietf-netconf-system-notifications-00.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 == Line 245 has weird spacing: '...startup confi...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (September 3, 2010) is 4983 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 510, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-yang-types' is defined on line 524, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) Summary: 1 error (**), 0 flaws (~~), 5 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 September 3, 2010 5 Expires: March 7, 2011 7 NETCONF System Notifications 8 draft-ietf-netconf-system-notifications-00 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 March 7, 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 . . . . . . . . . . . . . . . . . . . . . 12 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 62 5. Normative References . . . . . . . . . . . . . . . . . . . . . 12 63 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 12 64 A.1. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 1. Introduction 69 The NETCONF protocol [RFC4741] provides mechanisms to manipulate 70 configuration datastores. However, client applications often need to 71 be aware of common system events such as a change in system 72 capabilities, which may impact management applications. Standard 73 mechanisms are needed to support the monitoring of the system events 74 within the NETCONF server. This document defines a YANG module 75 [I-D.ietf-netmod-yang] which allows a NETCONF client to receive 76 notifications for some common system events. 78 1.1. Terminology 80 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 81 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 82 document are to be interpreted as described in [RFC2119]. 84 The following terms are defined in [RFC4741]: 85 o client 86 o datastore 87 o operation 88 o server 90 The following terms are defined in [RFC5277]: 91 o event 92 o stream 93 o subscription 95 The following term is defined in [I-D.ietf-netmod-yang]: 96 o data node 98 2. YANG Module for System Notifications 100 2.1. Overview 102 The YANG module defined within this document specifies a small number 103 of notification event messages for use within the 'NETCONF' stream, 104 and accessible to clients via the subscription mechanism in 105 [RFC5277]. 107 The YANG language is defined in [I-D.ietf-netmod-yang]. 109 2.1.1. Notifications 111 This module defines some system events to notify a client application 112 that the system state has changed. 114 o sys-startup: Generated during a system restart. Lists any errors 115 that were encountered while loading the datastore during 116 system initialization. 117 o sys-config-change: Generated when the configuration 118 datastore is changed. Summarizes each edit being reported. 119 o sys-capability-change: Generated when the NETCONF server 120 capabilities are changed. Indicates which capabilities have been 121 added, deleted, and/or modified. 122 o sys-session-start: Generated when the NETCONF session is started. 123 Indicates the identity of the user that started the session. 124 o sys-session-end: Generated when the NETCONF session is terminated. 125 Indicates the identity of the user that owned the session, and why 126 the session was terminated. 127 o sys-conformed-commit: Generated when the NETCONF confirmed-commit 128 event occurs. Indicates the current state of the confirmed-commit 129 operation in progress. 131 2.2. Definitions 133 file="ietf-netconf-system-notifications@2010-09-03.yang" 135 module ietf-netconf-system-notifications { 137 namespace 138 "urn:ietf:params:xml:ns:yang:ietf-netconf-system-notifications"; 140 prefix nc-sys-notif; 142 import ietf-yang-types { prefix yang; } 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 system 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-00.txt 185 revision 2010-09-03 { 186 description 187 "Initial version."; 188 reference 189 "RFC XXXX: NETCONF System Notifications"; 190 } 191 // RFC Ed.: replace XXXX with actual 192 // RFC number and remove this note 194 typedef error-type-type { 195 description "NETCONF Error Type"; 196 type enumeration { 197 enum transport { 198 description "Transport layer error"; 199 } 200 enum rpc { 201 description "Operation layer error"; 202 } 203 enum protocol { 204 description "Protocol layer error"; 205 } 206 enum application { 207 description "Application layer error"; 209 } 210 } 211 } 213 grouping sys-common-session-parms { 215 leaf user-name { 216 description 217 "Name of the user for the session."; 218 type string; 219 } 221 leaf session-id { 222 description "Identifier of the session."; 223 type nc:session-id-or-zero-type; 224 mandatory true; 225 } 227 leaf remote-host { 228 description 229 "Address of the remote host for the session."; 230 type inet:ip-address; 231 } 232 } 234 notification sys-startup { 235 description 236 "Generated when the system restarts. 237 Used for logging purposes, since no 238 sessions are actually active when 239 the system restarts."; 241 leaf startup-source { 242 description 243 "The system-specific filespec used to load the 244 running configuration. This leaf will only be 245 present if there was a startup configuration file used."; 246 type string; 247 } 249 list boot-error { 250 description 251 "There will be one entry for each 252 encountered during the load config operation. 253 There is no particular order, so no key is defined. 254 This list will only be present if the server is configured 255 to continue on error during startup, and there were recoverable 256 errors encountered during the last restart of the server."; 258 leaf error-type { 259 description 260 "Defines the conceptual layer that the error occurred."; 261 type error-type-type; 262 mandatory true; 263 } 265 leaf error-tag { 266 description 267 "Contains a string identifying the error condition."; 268 type nc:error-tag-type; 269 mandatory true; 270 } 272 leaf error-severity { 273 description 274 "Contains a string identifying the error severity, as 275 determined by the device."; 276 type nc:error-severity-type; 277 mandatory true; 278 } 280 leaf error-app-tag { 281 description 282 "Contains a string identifying the data-model-specific 283 or implementation-specific error condition, if one exists."; 284 type string; 285 } 287 leaf error-path { 288 description 289 "Contains the absolute XPath expression identifying 290 the element path to the node that is associated with 291 the error being reported in a particular 292 element."; 293 type yang:xpath1.0; 294 } 296 leaf error-message { 297 description 298 "Contains a string suitable for human display that 299 describes the error condition."; 300 type string; // LangString; 301 } 303 anyxml error-info { 304 description 305 "Contains protocol- or data-model-specific error content."; 307 } 308 } // list boot-error 309 } // notification sys-startup 311 notification sys-config-change { 312 description 313 "Generated when the configuration is changed."; 314 uses sys-common-session-parms; 316 list edit { 317 description 318 "An edit record will be present for each distinct 319 edit operation on the running config."; 320 leaf target { 321 type instance-identifier; 322 description 323 "Topmost node associated with the configuration change."; 324 } 326 leaf operation { 327 type nc:edit-operation-type; 328 description "Type of edit operation performed."; 329 } 330 } // list edit 331 } // notification sys-config-change 333 notification sys-capability-change { 334 description 335 "Generated when a is added, deleted, 336 or modified."; 337 container changed-by { 338 description 339 "Indicates who caused this capability change. 340 If caused by internal action, then the 341 empty leaf 'server' will be present. 342 If caused by a management session, then 343 the name, remote host address, and session ID 344 of the session that made the change will be reported."; 345 choice server-or-user { 346 leaf server { 347 type empty; 348 description 349 "If present, the capability change was caused 350 by the server."; 351 } 352 case by-user { 353 uses sys-common-session-parms; 354 } // case by-user 355 } // choice server-or-user 356 } // container changed-by 358 leaf-list added-capability { 359 type inet:uri; 360 description 361 "List of capabilities that have just been added."; 362 } 364 leaf-list deleted-capability { 365 type inet:uri; 366 description 367 "List of capabilities that have just been deleted."; 368 } 370 leaf-list modified-capability { 371 type inet:uri; 372 description 373 "List of capabilities that have just been modified."; 374 } 375 } // notification sys-capability-change 377 notification sys-session-start { 378 description 379 "Generated when a new NETCONF session is started."; 380 uses sys-common-session-parms; 381 } // notification sys-session-start 383 notification sys-session-end { 384 description 385 "Generated when a NETCONF session is terminated."; 386 uses sys-common-session-parms; 388 leaf killed-by { 389 when "../termination-reason = 'killed'"; 390 type nc:session-id-type; 391 description 392 "Session ID that issued the 393 if the session was terminated by this operation."; 394 } 396 leaf termination-reason { 397 type enumeration { 398 enum "closed" { 399 value 0; 400 description 401 "The session was terminated with 402 the operation."; 403 } 404 enum "killed" { 405 value 1; 406 description 407 "The session was terminated with 408 the operation."; 409 } 410 enum "dropped" { 411 value 2; 412 description 413 "The session was terminated because 414 the SSH session or TCP connection was 415 unexpectedly closed."; 416 } 417 enum "timeout" { 418 value 3; 419 description 420 "The session was terminated because 421 of inactivity, either waiting for 422 the or messages."; 423 } 424 enum "bad-start" { 425 value 4; 426 description "The session startup sequence failed."; 427 } 428 enum "bad-hello" { 429 value 5; 430 description 431 "The client's message was 432 bad or never arrived."; 433 } 434 enum "other" { 435 value 6; 436 description 437 "The session was terminated for 438 some other reason."; 439 } 440 } 441 mandatory "true"; 442 description "Reason the session was terminated."; 443 } 444 } // notification sys-session-end 445 notification sys-confirmed-commit { 446 description 447 "Generated when a confirmed-commit event occurs."; 448 uses sys-common-session-parms; 450 leaf confirm-event { 451 description 452 "Indicates the event that caused the notification."; 453 type enumeration { 454 enum "start" { 455 value 0; 456 description 457 "The confirm-commit procedure has started."; 458 } 459 enum "cancel" { 460 value 1; 461 description 462 "The confirm-commit procedure has been canceled, 463 due to the session being terminated."; 464 } 465 enum "timeout" { 466 value 2; 467 description 468 "The confirm-commit procedure has been canceled, 469 due to the confirm-timeout interval expiring. 470 The common session parameters will not be present 471 in this sub-mode."; 472 } 473 enum "extend" { 474 value 3; 475 description 476 "The confirm-commit timeout has been extended."; 477 } 478 enum "complete" { 479 value 4; 480 description 481 "The confirm-commit procedure has been completed."; 482 } 483 } 484 mandatory "true"; 485 } 486 } // notification sys-confirmed-commit 488 } 490 492 3. IANA Considerations 494 TBD 496 4. Security Considerations 498 This document defines a YANG module for reporting of particular 499 system events. Although unlikely, it is possible that data obtained 500 from this module could be used in an attack of some kind, although no 501 specific information in this module is considered sensitive. 503 TBD: follow Security Consideration guidelines from new template text. 505 5. Normative References 507 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 508 Requirement Levels", BCP 14, RFC 2119, March 1997. 510 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 511 January 2004. 513 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 514 December 2006. 516 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 517 Notifications", RFC 5277, July 2008. 519 [I-D.ietf-netmod-yang] 520 Bjorklund, M., "YANG - A data modeling language for the 521 Network Configuration Protocol (NETCONF)", 522 draft-ietf-netmod-yang-13 (work in progress), June 2010. 524 [I-D.ietf-netmod-yang-types] 525 Schoenwaelder, J., "Common YANG Data Types", 526 draft-ietf-netmod-yang-types-09 (work in progress), 527 April 2010. 529 Appendix A. Change Log 531 -- RFC Ed.: remove this section before publication. 533 A.1. 00 535 Initial version, based on 536 draft-bierman-netconf-system-monitoring-00.txt. 538 Author's Address 540 Andy Bierman 541 Brocade 543 Email: andy.bierman@brocade.com